pdfx-cli 0.0.1 → 0.4.0

package/dist/index.js

@@ -0,0 +1,4429 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import chalk10 from "chalk";
+import { Command as Command3 } from "commander";
+
+// src/commands/add.ts
+import fs5 from "fs";
+import path4 from "path";
+
+// ../shared/src/schemas.ts
+import { z } from "zod";
+var colorTokensSchema = z.object({
+  foreground: z.string().min(1),
+  background: z.string().min(1),
+  muted: z.string().min(1),
+  mutedForeground: z.string().min(1),
+  primary: z.string().min(1),
+  primaryForeground: z.string().min(1),
+  border: z.string().min(1),
+  accent: z.string().min(1),
+  destructive: z.string().min(1),
+  success: z.string().min(1),
+  warning: z.string().min(1),
+  info: z.string().min(1)
+});
+var headingFontSizeSchema = z.object({
+  h1: z.number().positive(),
+  h2: z.number().positive(),
+  h3: z.number().positive(),
+  h4: z.number().positive(),
+  h5: z.number().positive(),
+  h6: z.number().positive()
+});
+var typographyTokensSchema = z.object({
+  body: z.object({
+    fontFamily: z.string().min(1),
+    fontSize: z.number().positive(),
+    lineHeight: z.number().positive()
+  }),
+  heading: z.object({
+    fontFamily: z.string().min(1),
+    fontWeight: z.number().int().min(100).max(900),
+    lineHeight: z.number().positive(),
+    fontSize: headingFontSizeSchema
+  })
+});
+var spacingTokensSchema = z.object({
+  page: z.object({
+    marginTop: z.number().min(0),
+    marginRight: z.number().min(0),
+    marginBottom: z.number().min(0),
+    marginLeft: z.number().min(0)
+  }),
+  sectionGap: z.number().min(0),
+  paragraphGap: z.number().min(0),
+  componentGap: z.number().min(0)
+});
+var pageTokensSchema = z.object({
+  size: z.enum(["A4", "LETTER", "LEGAL"]),
+  orientation: z.enum(["portrait", "landscape"])
+});
+var primitiveTokensSchema = z.object({
+  typography: z.record(z.number()),
+  spacing: z.record(z.number()),
+  fontWeights: z.object({
+    regular: z.number(),
+    medium: z.number(),
+    semibold: z.number(),
+    bold: z.number()
+  }),
+  lineHeights: z.object({
+    tight: z.number(),
+    normal: z.number(),
+    relaxed: z.number()
+  }),
+  borderRadius: z.object({
+    none: z.number(),
+    sm: z.number(),
+    md: z.number(),
+    lg: z.number(),
+    full: z.number()
+  }),
+  letterSpacing: z.object({
+    tight: z.number(),
+    normal: z.number(),
+    wide: z.number(),
+    wider: z.number()
+  })
+});
+var themeSchema = z.object({
+  name: z.string().min(1),
+  primitives: primitiveTokensSchema,
+  colors: colorTokensSchema,
+  typography: typographyTokensSchema,
+  spacing: spacingTokensSchema,
+  page: pageTokensSchema
+});
+var configSchema = z.object({
+  $schema: z.string().optional(),
+  componentDir: z.string().min(1, "componentDir must not be empty"),
+  registry: z.string().url("registry must be a valid URL"),
+  theme: z.string().min(1).optional(),
+  blockDir: z.string().min(1).optional()
+});
+var registryFileTypes = [
+  "registry:component",
+  "registry:lib",
+  "registry:style",
+  "registry:template",
+  "registry:block",
+  "registry:file"
+];
+var registryFileSchema = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+  type: z.enum(registryFileTypes)
+});
+var registryItemSchema = z.object({
+  name: z.string().min(1),
+  type: z.string().optional(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  files: z.array(registryFileSchema).min(1, "Component must have at least one file"),
+  dependencies: z.array(z.string()).optional(),
+  devDependencies: z.array(z.string()).optional(),
+  registryDependencies: z.array(z.string()).optional(),
+  peerComponents: z.array(z.string()).optional()
+});
+var registryIndexItemSchema = z.object({
+  name: z.string().min(1),
+  type: z.string(),
+  title: z.string(),
+  description: z.string(),
+  files: z.array(
+    z.object({
+      path: z.string().min(1),
+      type: z.string()
+    })
+  ),
+  dependencies: z.array(z.string()).optional(),
+  devDependencies: z.array(z.string()).optional(),
+  registryDependencies: z.array(z.string()).optional(),
+  peerComponents: z.array(z.string()).optional()
+});
+var registrySchema = z.object({
+  $schema: z.string(),
+  name: z.string(),
+  homepage: z.string(),
+  items: z.array(registryIndexItemSchema)
+});
+var componentNameSchema = z.string().regex(
+  /^[a-z][a-z0-9-]*$/,
+  "Component name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens"
+);
+
+// ../shared/src/themes/primitives.ts
+var defaultPrimitives = {
+  typography: {
+    xs: 10,
+    sm: 12,
+    base: 15,
+    lg: 18,
+    xl: 22,
+    "2xl": 28,
+    "3xl": 36
+  },
+  spacing: {
+    0: 0,
+    0.5: 2,
+    1: 4,
+    2: 8,
+    3: 12,
+    4: 16,
+    5: 20,
+    6: 24,
+    8: 32,
+    10: 40,
+    12: 48,
+    16: 64
+  },
+  fontWeights: {
+    regular: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700
+  },
+  lineHeights: {
+    tight: 1.2,
+    normal: 1.4,
+    relaxed: 1.6
+  },
+  borderRadius: {
+    none: 0,
+    sm: 2,
+    md: 4,
+    lg: 8,
+    full: 9999
+  },
+  letterSpacing: {
+    tight: -0.025,
+    normal: 0,
+    wide: 0.025,
+    wider: 0.05
+  }
+};
+
+// ../shared/src/themes/professional.ts
+var professionalTheme = {
+  name: "professional",
+  primitives: defaultPrimitives,
+  colors: {
+    foreground: "#18181b",
+    background: "#ffffff",
+    muted: "#f4f4f5",
+    mutedForeground: "#71717a",
+    primary: "#18181b",
+    primaryForeground: "#ffffff",
+    border: "#e4e4e7",
+    accent: "#3b82f6",
+    destructive: "#dc2626",
+    success: "#16a34a",
+    warning: "#d97706",
+    info: "#0ea5e9"
+  },
+  typography: {
+    body: {
+      fontFamily: "Helvetica",
+      fontSize: 11,
+      lineHeight: 1.6
+    },
+    heading: {
+      fontFamily: "Times-Roman",
+      fontWeight: 700,
+      lineHeight: 1.25,
+      fontSize: {
+        h1: 32,
+        h2: 24,
+        h3: 20,
+        h4: 16,
+        h5: 14,
+        h6: 12
+      }
+    }
+  },
+  spacing: {
+    page: {
+      marginTop: 56,
+      marginRight: 48,
+      marginBottom: 56,
+      marginLeft: 48
+    },
+    sectionGap: 28,
+    paragraphGap: 10,
+    componentGap: 14
+  },
+  page: {
+    size: "A4",
+    orientation: "portrait"
+  }
+};
+
+// ../shared/src/themes/modern.ts
+var modernTheme = {
+  name: "modern",
+  primitives: defaultPrimitives,
+  colors: {
+    foreground: "#0f172a",
+    background: "#ffffff",
+    muted: "#f1f5f9",
+    mutedForeground: "#64748b",
+    primary: "#334155",
+    primaryForeground: "#ffffff",
+    border: "#e2e8f0",
+    accent: "#6366f1",
+    destructive: "#ef4444",
+    success: "#22c55e",
+    warning: "#f59e0b",
+    info: "#3b82f6"
+  },
+  typography: {
+    body: {
+      fontFamily: "Helvetica",
+      fontSize: 11,
+      lineHeight: 1.6
+    },
+    heading: {
+      fontFamily: "Helvetica",
+      fontWeight: 600,
+      lineHeight: 1.25,
+      fontSize: {
+        h1: 28,
+        h2: 22,
+        h3: 18,
+        h4: 16,
+        h5: 14,
+        h6: 12
+      }
+    }
+  },
+  spacing: {
+    page: {
+      marginTop: 40,
+      marginRight: 40,
+      marginBottom: 40,
+      marginLeft: 40
+    },
+    sectionGap: 24,
+    paragraphGap: 10,
+    componentGap: 12
+  },
+  page: {
+    size: "A4",
+    orientation: "portrait"
+  }
+};
+
+// ../shared/src/themes/minimal.ts
+var minimalTheme = {
+  name: "minimal",
+  primitives: defaultPrimitives,
+  colors: {
+    foreground: "#18181b",
+    background: "#ffffff",
+    muted: "#fafafa",
+    mutedForeground: "#a1a1aa",
+    primary: "#18181b",
+    primaryForeground: "#ffffff",
+    border: "#e4e4e7",
+    accent: "#71717a",
+    destructive: "#b91c1c",
+    success: "#15803d",
+    warning: "#a16207",
+    info: "#0369a1"
+  },
+  typography: {
+    body: {
+      fontFamily: "Helvetica",
+      fontSize: 11,
+      lineHeight: 1.65
+    },
+    heading: {
+      fontFamily: "Courier",
+      fontWeight: 600,
+      lineHeight: 1.25,
+      fontSize: {
+        h1: 24,
+        h2: 20,
+        h3: 16,
+        h4: 14,
+        h5: 12,
+        h6: 10
+      }
+    }
+  },
+  spacing: {
+    page: {
+      marginTop: 72,
+      marginRight: 56,
+      marginBottom: 72,
+      marginLeft: 56
+    },
+    sectionGap: 36,
+    paragraphGap: 14,
+    componentGap: 18
+  },
+  page: {
+    size: "A4",
+    orientation: "portrait"
+  }
+};
+
+// ../shared/src/themes/index.ts
+var themePresets = {
+  professional: professionalTheme,
+  modern: modernTheme,
+  minimal: minimalTheme
+};
+
+// ../shared/src/errors.ts
+var PdfxError = class extends Error {
+  constructor(message, code, suggestion) {
+    super(message);
+    this.code = code;
+    this.suggestion = suggestion;
+    this.name = "PdfxError";
+  }
+};
+var ConfigError = class extends PdfxError {
+  constructor(message, suggestion) {
+    super(message, "CONFIG_ERROR", suggestion);
+    this.name = "ConfigError";
+  }
+};
+var RegistryError = class extends PdfxError {
+  constructor(message, suggestion) {
+    super(message, "REGISTRY_ERROR", suggestion);
+    this.name = "RegistryError";
+  }
+};
+var NetworkError = class extends PdfxError {
+  constructor(message, suggestion) {
+    super(
+      message,
+      "NETWORK_ERROR",
+      suggestion ?? "Check your internet connection and registry URL"
+    );
+    this.name = "NetworkError";
+  }
+};
+var ValidationError = class extends PdfxError {
+  constructor(message, suggestion) {
+    super(message, "VALIDATION_ERROR", suggestion);
+    this.name = "ValidationError";
+  }
+};
+
+// src/commands/add.ts
+import chalk from "chalk";
+import { execa } from "execa";
+import ora from "ora";
+import prompts from "prompts";
+
+// src/constants.ts
+var DEFAULTS = {
+  REGISTRY_URL: "https://pdfx.akashpise.dev/r",
+  SCHEMA_URL: "https://pdfx.akashpise.dev/schema.json",
+  COMPONENT_DIR: "./src/components/pdfx",
+  THEME_FILE: "./src/lib/pdfx-theme.ts",
+  BLOCK_DIR: "./src/blocks/pdfx"
+};
+var REGISTRY_SUBPATHS = {
+  BLOCKS: "blocks"
+};
+var REQUIRED_VERSIONS = {
+  "@react-pdf/renderer": ">=3.0.0",
+  react: ">=16.8.0",
+  node: ">=20.0.0"
+};
+var FETCH_TIMEOUT_MS = 1e4;
+
+// src/utils/dependency-validator.ts
+import fs2 from "fs";
+import path from "path";
+import semver from "semver";
+
+// src/utils/read-json.ts
+import fs from "fs";
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (error) {
+    const details = error instanceof Error ? error.message : String(error);
+    throw new ConfigError(`Failed to read ${filePath}: ${details}`);
+  }
+}
+
+// src/utils/dependency-validator.ts
+function getPackageJson(cwd = process.cwd()) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs2.existsSync(pkgPath)) {
+    return null;
+  }
+  return readJsonFile(pkgPath);
+}
+function getInstalledVersion(packageName, cwd = process.cwd(), pkg) {
+  const resolved = pkg !== void 0 ? pkg : getPackageJson(cwd);
+  if (!resolved) return null;
+  const deps = {
+    ...resolved.dependencies,
+    ...resolved.devDependencies
+  };
+  const version = deps[packageName];
+  if (!version) return null;
+  return semver.clean(version) || semver.coerce(version)?.version || null;
+}
+function validateReactPdfRenderer(cwd = process.cwd(), pkg) {
+  const version = getInstalledVersion("@react-pdf/renderer", cwd, pkg);
+  const required = REQUIRED_VERSIONS["@react-pdf/renderer"];
+  if (!version) {
+    return {
+      valid: false,
+      installed: false,
+      requiredVersion: required,
+      message: "@react-pdf/renderer is not installed"
+    };
+  }
+  const isCompatible = semver.satisfies(version, required);
+  return {
+    valid: isCompatible,
+    installed: true,
+    currentVersion: version,
+    requiredVersion: required,
+    message: isCompatible ? "@react-pdf/renderer version is compatible" : `@react-pdf/renderer version ${version} does not meet requirement ${required}`
+  };
+}
+function validateReact(cwd = process.cwd(), pkg) {
+  const version = getInstalledVersion("react", cwd, pkg);
+  const required = REQUIRED_VERSIONS.react;
+  if (!version) {
+    return {
+      valid: false,
+      installed: false,
+      requiredVersion: required,
+      message: "React is not installed"
+    };
+  }
+  const isCompatible = semver.satisfies(version, required);
+  return {
+    valid: isCompatible,
+    installed: true,
+    currentVersion: version,
+    requiredVersion: required,
+    message: isCompatible ? "React version is compatible" : `React version ${version} does not meet requirement ${required}`
+  };
+}
+function validateNodeVersion() {
+  const version = process.version;
+  const required = REQUIRED_VERSIONS.node;
+  const cleanVersion = semver.clean(version);
+  if (!cleanVersion) {
+    return {
+      valid: false,
+      installed: true,
+      currentVersion: version,
+      requiredVersion: required,
+      message: `Unable to parse Node.js version: ${version}`
+    };
+  }
+  const isCompatible = semver.satisfies(cleanVersion, required);
+  return {
+    valid: isCompatible,
+    installed: true,
+    currentVersion: cleanVersion,
+    requiredVersion: required,
+    message: isCompatible ? "Node.js version is compatible" : `Node.js version ${cleanVersion} does not meet requirement ${required}`
+  };
+}
+function validateDependencies(cwd = process.cwd()) {
+  const pkg = getPackageJson(cwd);
+  return {
+    reactPdfRenderer: validateReactPdfRenderer(cwd, pkg),
+    react: validateReact(cwd, pkg),
+    nodeJs: validateNodeVersion()
+  };
+}
+
+// src/utils/file-system.ts
+import fs3 from "fs";
+import path2 from "path";
+function ensureDir(dir) {
+  fs3.mkdirSync(dir, { recursive: true });
+}
+function writeFile(filePath, content) {
+  const dir = path2.dirname(filePath);
+  ensureDir(dir);
+  fs3.writeFileSync(filePath, content, "utf-8");
+}
+function checkFileExists(filePath) {
+  return fs3.existsSync(filePath);
+}
+function normalizePath(...segments) {
+  return path2.resolve(...segments);
+}
+function isPathWithinDirectory(resolvedPath, targetDir) {
+  const normalizedTarget = normalizePath(targetDir);
+  const normalizedResolved = normalizePath(resolvedPath);
+  if (normalizedResolved === normalizedTarget) return true;
+  const prefix = normalizedTarget.endsWith(path2.sep) ? normalizedTarget : normalizedTarget + path2.sep;
+  return normalizedResolved.startsWith(prefix);
+}
+function safePath(targetDir, fileName) {
+  const resolved = normalizePath(targetDir, fileName);
+  const normalizedTarget = normalizePath(targetDir);
+  if (!isPathWithinDirectory(resolved, normalizedTarget)) {
+    throw new Error(`Path "${fileName}" escapes target directory "${normalizedTarget}"`);
+  }
+  return resolved;
+}
+
+// src/utils/generate-theme.ts
+function generateThemeFile(preset) {
+  return `// Generated by pdfx init.
+// See: https://pdfx.akashpise.dev/installation#theming
+//
+// This module is the single source of truth for PDFX styling tokens.
+// Update the exported \`theme\` object to customize component styles.
+
+interface PdfxTheme {
+  name: string;
+  primitives: {
+    typography: Record<string, number>;
+    spacing: Record<string | number, number>;
+    fontWeights: { regular: number; medium: number; semibold: number; bold: number };
+    lineHeights: { tight: number; normal: number; relaxed: number };
+    borderRadius: { none: number; sm: number; md: number; lg: number; full: number };
+    letterSpacing: { tight: number; normal: number; wide: number; wider: number };
+  };
+  colors: {
+    foreground: string;
+    background: string;
+    muted: string;
+    mutedForeground: string;
+    primary: string;
+    primaryForeground: string;
+    border: string;
+    accent: string;
+    destructive: string;
+    success: string;
+    warning: string;
+    info: string;
+  };
+  typography: {
+    body: { fontFamily: string; fontSize: number; lineHeight: number };
+    heading: {
+      fontFamily: string;
+      fontWeight: number;
+      lineHeight: number;
+      fontSize: { h1: number; h2: number; h3: number; h4: number; h5: number; h6: number };
+    };
+  };
+  spacing: {
+    page: { marginTop: number; marginRight: number; marginBottom: number; marginLeft: number };
+    sectionGap: number;
+    paragraphGap: number;
+    componentGap: number;
+  };
+  page: {
+    size: 'A4' | 'LETTER' | 'LEGAL';
+    orientation: 'portrait' | 'landscape';
+  };
+}
+
+export const theme: PdfxTheme = ${serializeTheme(preset)};
+`;
+}
+function serializeTheme(t) {
+  return `{
+  name: '${t.name}',
+
+  // Primitive scales.
+  primitives: {
+    typography: {
+      xs: ${t.primitives.typography.xs},
+      sm: ${t.primitives.typography.sm},
+      base: ${t.primitives.typography.base},
+      lg: ${t.primitives.typography.lg},
+      xl: ${t.primitives.typography.xl},
+      '2xl': ${t.primitives.typography["2xl"]},
+      '3xl': ${t.primitives.typography["3xl"]},
+    },
+    spacing: {
+      0: ${t.primitives.spacing[0]},
+      0.5: ${t.primitives.spacing[0.5]},
+      1: ${t.primitives.spacing[1]},
+      2: ${t.primitives.spacing[2]},
+      3: ${t.primitives.spacing[3]},
+      4: ${t.primitives.spacing[4]},
+      5: ${t.primitives.spacing[5]},
+      6: ${t.primitives.spacing[6]},
+      8: ${t.primitives.spacing[8]},
+      10: ${t.primitives.spacing[10]},
+      12: ${t.primitives.spacing[12]},
+      16: ${t.primitives.spacing[16]},
+    },
+    fontWeights: {
+      regular: ${t.primitives.fontWeights.regular},
+      medium: ${t.primitives.fontWeights.medium},
+      semibold: ${t.primitives.fontWeights.semibold},
+      bold: ${t.primitives.fontWeights.bold},
+    },
+    lineHeights: {
+      tight: ${t.primitives.lineHeights.tight},
+      normal: ${t.primitives.lineHeights.normal},
+      relaxed: ${t.primitives.lineHeights.relaxed},
+    },
+    borderRadius: {
+      none: ${t.primitives.borderRadius.none},
+      sm: ${t.primitives.borderRadius.sm},
+      md: ${t.primitives.borderRadius.md},
+      lg: ${t.primitives.borderRadius.lg},
+      full: ${t.primitives.borderRadius.full},
+    },
+    letterSpacing: {
+      tight: ${t.primitives.letterSpacing.tight},
+      normal: ${t.primitives.letterSpacing.normal},
+      wide: ${t.primitives.letterSpacing.wide},
+      wider: ${t.primitives.letterSpacing.wider},
+    },
+  },
+
+  // Semantic colors. Values must be valid for react-pdf.
+  colors: {
+    foreground: '${t.colors.foreground}',
+    background: '${t.colors.background}',
+    muted: '${t.colors.muted}',
+    mutedForeground: '${t.colors.mutedForeground}',
+    primary: '${t.colors.primary}',
+    primaryForeground: '${t.colors.primaryForeground}',
+    border: '${t.colors.border}',
+    accent: '${t.colors.accent}',
+    destructive: '${t.colors.destructive}',
+    success: '${t.colors.success}',
+    warning: '${t.colors.warning}',
+    info: '${t.colors.info}',
+  },
+
+  // Typography defaults.
+  typography: {
+    body: {
+      fontFamily: '${t.typography.body.fontFamily}',
+      fontSize: ${t.typography.body.fontSize},
+      lineHeight: ${t.typography.body.lineHeight},
+    },
+    heading: {
+      fontFamily: '${t.typography.heading.fontFamily}',
+      fontWeight: ${t.typography.heading.fontWeight},
+      lineHeight: ${t.typography.heading.lineHeight},
+      fontSize: {
+        h1: ${t.typography.heading.fontSize.h1},
+        h2: ${t.typography.heading.fontSize.h2},
+        h3: ${t.typography.heading.fontSize.h3},
+        h4: ${t.typography.heading.fontSize.h4},
+        h5: ${t.typography.heading.fontSize.h5},
+        h6: ${t.typography.heading.fontSize.h6},
+      },
+    },
+  },
+
+  // Layout spacing.
+  spacing: {
+    page: {
+      marginTop: ${t.spacing.page.marginTop},
+      marginRight: ${t.spacing.page.marginRight},
+      marginBottom: ${t.spacing.page.marginBottom},
+      marginLeft: ${t.spacing.page.marginLeft},
+    },
+    sectionGap: ${t.spacing.sectionGap},
+    paragraphGap: ${t.spacing.paragraphGap},
+    componentGap: ${t.spacing.componentGap},
+  },
+
+  // Page defaults.
+  page: {
+    size: '${t.page.size}',
+    orientation: '${t.page.orientation}',
+  },
+}`;
+}
+function generateThemeContextFile() {
+  return `// Generated by pdfx init.
+// See: https://pdfx.akashpise.dev/installation#theming
+//
+// Provides runtime theme overrides via React context.
+// Wrap a subtree in <PdfxThemeProvider theme={myTheme}> to override defaults.
+
+/* eslint-disable react-refresh/only-export-components */
+// Intentional: this module exports both a component and hooks/context.
+// Keeping a single import surface preserves the generated public API.
+
+import { type DependencyList, type ReactNode, createContext, useContext } from 'react';
+import { theme as defaultTheme } from './pdfx-theme';
+
+type PdfxTheme = typeof defaultTheme;
+
+export const PdfxThemeContext = createContext<PdfxTheme>(defaultTheme);
+
+export interface PdfxThemeProviderProps {
+  theme?: PdfxTheme;
+  children: ReactNode;
+}
+
+export function PdfxThemeProvider({ theme, children }: PdfxThemeProviderProps) {
+  const resolvedTheme = theme ?? defaultTheme;
+  return <PdfxThemeContext.Provider value={resolvedTheme}>{children}</PdfxThemeContext.Provider>;
+}
+
+/**
+ * Returns the active theme from context.
+ *
+ * When called outside a React render tree (for example in plain-function tests),
+ * React may throw an invalid hook error. In that case we return defaultTheme.
+ * Unexpected errors are re-thrown.
+ */
+export function usePdfxTheme(): PdfxTheme {
+  try {
+    return useContext(PdfxThemeContext);
+  } catch (error) {
+    // Suppress only known React dispatcher errors.
+    if (
+      error instanceof Error &&
+      /invalid hook call|useContext|cannot read properties of null/i.test(error.message)
+    ) {
+      return defaultTheme;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Calls factory() and returns the result.
+ * The deps parameter is accepted for API compatibility with existing callers.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function useSafeMemo<T>(factory: () => T, _deps: DependencyList): T {
+  return factory();
+}
+`;
+}
+
+// src/utils/package-manager.ts
+import fs4 from "fs";
+import path3 from "path";
+var PACKAGE_MANAGERS = {
+  pnpm: {
+    name: "pnpm",
+    lockfile: "pnpm-lock.yaml",
+    installCommand: "pnpm add"
+  },
+  yarn: {
+    name: "yarn",
+    lockfile: "yarn.lock",
+    installCommand: "yarn add"
+  },
+  bun: {
+    name: "bun",
+    lockfile: "bun.lock",
+    installCommand: "bun add"
+  },
+  npm: {
+    name: "npm",
+    lockfile: "package-lock.json",
+    installCommand: "npm install"
+  }
+};
+function findPackageRoot(startDir) {
+  let dir = path3.resolve(startDir);
+  const fsRoot = path3.parse(dir).root;
+  while (dir !== fsRoot) {
+    const pkgPath = path3.join(dir, "package.json");
+    if (fs4.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
+        const hasWorkspacesField = Array.isArray(pkg.workspaces) || typeof pkg.workspaces === "object" && pkg.workspaces !== null;
+        const hasPnpmWorkspaceFile = fs4.existsSync(path3.join(dir, "pnpm-workspace.yaml"));
+        if (!hasWorkspacesField && !hasPnpmWorkspaceFile) {
+          return dir;
+        }
+      } catch {
+        return dir;
+      }
+    }
+    dir = path3.dirname(dir);
+  }
+  return startDir;
+}
+function detectPackageManager(startDir = process.cwd()) {
+  const managers = ["pnpm", "yarn", "bun", "npm"];
+  let dir = path3.resolve(startDir);
+  const fsRoot = path3.parse(dir).root;
+  while (dir !== fsRoot) {
+    for (const manager of managers) {
+      const info = PACKAGE_MANAGERS[manager];
+      if (fs4.existsSync(path3.join(dir, info.lockfile))) {
+        return info;
+      }
+    }
+    if (fs4.existsSync(path3.join(dir, "bun.lockb"))) {
+      return PACKAGE_MANAGERS.bun;
+    }
+    dir = path3.dirname(dir);
+  }
+  return PACKAGE_MANAGERS.npm;
+}
+function getInstallCommand(packageManager, packages, devDependency = false) {
+  const pm = PACKAGE_MANAGERS[packageManager];
+  const devFlag = devDependency ? packageManager === "npm" ? "--save-dev" : "-D" : "";
+  return `${pm.installCommand} ${packages.join(" ")} ${devFlag}`.trim();
+}
+
+// src/commands/add.ts
+function readConfig(configPath) {
+  const raw = readJsonFile(configPath);
+  const result = configSchema.safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => {
+      const fieldPath = i.path.length > 0 ? i.path.join(".") : "root";
+      return `"${fieldPath}": ${i.message}`;
+    }).join("; ");
+    throw new ConfigError(
+      `Invalid pdfx.json: ${issues}`,
+      `Fix the config or re-run ${chalk.cyan("npx pdfx-cli@latest init")}`
+    );
+  }
+  return result.data;
+}
+async function fetchComponent(name, registryUrl) {
+  const url = `${registryUrl}/${name}.json`;
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  } catch (err) {
+    const isTimeout = err instanceof Error && err.name === "TimeoutError";
+    throw new NetworkError(
+      isTimeout ? `Registry request timed out after 10 seconds.
+  ${chalk.dim("Check your internet connection or try again later.")}` : `Could not reach registry at ${registryUrl}
+  ${chalk.dim("Verify the URL is correct and you have internet access.")}`
+    );
+  }
+  if (!response.ok) {
+    throw new RegistryError(
+      response.status === 404 ? `Component "${name}" not found in registry` : `Registry returned HTTP ${response.status}`
+    );
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new RegistryError(`Invalid response for "${name}": not valid JSON`);
+  }
+  const result = registryItemSchema.safeParse(data);
+  if (!result.success) {
+    throw new RegistryError(
+      `Invalid registry entry for "${name}": ${result.error.issues[0]?.message}`
+    );
+  }
+  return result.data;
+}
+function resolveThemeImport(componentDir, themePath, fileContent) {
+  const absComponentDir = path4.resolve(process.cwd(), componentDir);
+  const absThemePath = path4.resolve(process.cwd(), themePath);
+  const themeImportTarget = absThemePath.replace(/\.tsx?$/, "");
+  let relativePath = path4.relative(absComponentDir, themeImportTarget);
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+  const absContextPath = path4.join(path4.dirname(absThemePath), "pdfx-theme-context");
+  let relativeContextPath = path4.relative(absComponentDir, absContextPath);
+  if (!relativeContextPath.startsWith(".")) {
+    relativeContextPath = `./${relativeContextPath}`;
+  }
+  let content = fileContent.replace(
+    /from\s+['"]\.\.\/lib\/pdfx-theme['"]/g,
+    `from '${relativePath}'`
+  );
+  content = content.replace(
+    /from\s+['"]\.\.\/lib\/pdfx-theme-context['"]/g,
+    `from '${relativeContextPath}'`
+  );
+  return content;
+}
+function collectComponentDependencies(items) {
+  const runtime = /* @__PURE__ */ new Set();
+  const dev = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    for (const dep of item.dependencies ?? []) {
+      runtime.add(dep);
+    }
+    for (const dep of item.devDependencies ?? []) {
+      dev.add(dep);
+    }
+  }
+  return {
+    runtime: [...runtime],
+    dev: [...dev]
+  };
+}
+function getDeclaredDependencies(pkg) {
+  const deps = pkg.dependencies ?? {};
+  const devDeps = pkg.devDependencies ?? {};
+  return /* @__PURE__ */ new Set([...Object.keys(deps), ...Object.keys(devDeps)]);
+}
+function findMissingDependencies(requirements, pkg) {
+  const installed = getDeclaredDependencies(pkg);
+  return {
+    runtime: requirements.runtime.filter((dep) => !installed.has(dep)),
+    dev: requirements.dev.filter((dep) => !installed.has(dep))
+  };
+}
+function resolveDependencyInstallMode(options) {
+  if (options.installDeps === true) return "always";
+  if (options.installDeps === false) return "never";
+  return "prompt";
+}
+async function installDependencySet(packageRoot, runtimeDeps, devDeps) {
+  const pm = detectPackageManager(packageRoot);
+  const installArgs = pm.installCommand.split(" ").slice(1);
+  if (runtimeDeps.length > 0) {
+    await execa(pm.name, [...installArgs, ...runtimeDeps], {
+      cwd: packageRoot,
+      stdio: "pipe"
+    });
+  }
+  if (devDeps.length > 0) {
+    const devFlag = pm.name === "npm" ? "--save-dev" : "-D";
+    await execa(pm.name, [...installArgs, ...devDeps, devFlag], {
+      cwd: packageRoot,
+      stdio: "pipe"
+    });
+  }
+}
+function formatDependencyInstallHint(packageRoot, runtimeDeps, devDeps) {
+  const pm = detectPackageManager(packageRoot);
+  const commands = [];
+  if (runtimeDeps.length > 0) {
+    commands.push(getInstallCommand(pm.name, runtimeDeps));
+  }
+  if (devDeps.length > 0) {
+    commands.push(getInstallCommand(pm.name, devDeps, true));
+  }
+  return commands.map((cmd) => `  ${cmd}`).join("\n");
+}
+async function ensureComponentDependencies(requirements, options) {
+  const packageRoot = findPackageRoot(process.cwd());
+  const pkgPath = path4.join(packageRoot, "package.json");
+  if (!fs5.existsSync(pkgPath)) {
+    throw new ValidationError(
+      `Missing package.json at ${packageRoot}`,
+      "Run this command inside a Node.js project"
+    );
+  }
+  const pkg = readJsonFile(pkgPath);
+  const missing = findMissingDependencies(requirements, pkg);
+  if (missing.runtime.length === 0 && missing.dev.length === 0) {
+    return;
+  }
+  const installMode = resolveDependencyInstallMode(options);
+  const strictDeps = options.strictDeps ?? false;
+  const installHint = formatDependencyInstallHint(packageRoot, missing.runtime, missing.dev);
+  if (installMode === "never") {
+    const hasBlocking = missing.runtime.length > 0 || strictDeps && missing.dev.length > 0;
+    const missingMessage = [
+      missing.runtime.length > 0 ? `runtime: ${missing.runtime.join(", ")}` : void 0,
+      missing.dev.length > 0 ? `dev: ${missing.dev.join(", ")}` : void 0
+    ].filter(Boolean).join("; ");
+    if (hasBlocking) {
+      throw new ValidationError(
+        `Missing component dependencies (${missingMessage})`,
+        `Install manually:
+${installHint}`
+      );
+    }
+    console.log(
+      chalk.yellow(
+        `
+  \u26A0 Missing devDependencies (${missing.dev.join(", ")})
+  ${chalk.dim("\u2192")} Install manually:
+${chalk.cyan(installHint)}
+`
+      )
+    );
+    return;
+  }
+  let shouldInstall = installMode === "always";
+  if (installMode === "prompt") {
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive) {
+      throw new ValidationError(
+        "Missing component dependencies in non-interactive mode",
+        `Use --install-deps or install manually:
+${installHint}`
+      );
+    }
+    const depSummary = [
+      missing.runtime.length > 0 ? `runtime: ${missing.runtime.join(", ")}` : void 0,
+      missing.dev.length > 0 ? `dev: ${missing.dev.join(", ")}` : void 0
+    ].filter(Boolean).join("\n  ");
+    console.log(chalk.yellow("\n  Missing component dependencies detected:\n"));
+    console.log(chalk.dim(`  ${depSummary}
+`));
+    const response = await prompts({
+      type: "confirm",
+      name: "install",
+      message: "Install missing dependencies now?",
+      initial: true
+    });
+    shouldInstall = response.install === true;
+  }
+  if (!shouldInstall) {
+    throw new ValidationError(
+      "Dependency installation cancelled",
+      `Install manually:
+${installHint}`
+    );
+  }
+  const spinner = ora("Installing missing component dependencies...").start();
+  try {
+    await installDependencySet(packageRoot, missing.runtime, missing.dev);
+    spinner.succeed("Installed component dependencies");
+  } catch (error) {
+    spinner.fail("Failed to install component dependencies");
+    const message = error instanceof Error ? error.message : String(error);
+    if (strictDeps || missing.runtime.length > 0) {
+      throw new ValidationError(
+        `Dependency installation failed: ${message}`,
+        `Install manually:
+${installHint}`
+      );
+    }
+    console.log(
+      chalk.yellow(
+        `
+  \u26A0 Could not install devDependencies automatically
+  ${chalk.dim("\u2192")} Install manually:
+${chalk.cyan(installHint)}
+`
+      )
+    );
+  }
+}
+async function installComponent(component, config, force) {
+  const targetDir = path4.resolve(process.cwd(), config.componentDir);
+  const componentDir = path4.join(targetDir, component.name);
+  ensureDir(componentDir);
+  const componentRelDir = path4.join(config.componentDir, component.name);
+  const filesToWrite = [];
+  for (const file of component.files) {
+    const fileName = path4.basename(file.path);
+    const filePath = safePath(componentDir, fileName);
+    let content = file.content;
+    if (config.theme && (content.includes("pdfx-theme") || content.includes("pdfx-theme-context"))) {
+      content = resolveThemeImport(componentRelDir, config.theme, content);
+    }
+    filesToWrite.push({ filePath, content });
+  }
+  if (!force) {
+    const existing = filesToWrite.filter((f) => checkFileExists(f.filePath));
+    if (existing.length > 0) {
+      const fileNames = existing.map((f) => path4.basename(f.filePath)).join(", ");
+      throw new ValidationError(
+        `${component.name}: already exists (${fileNames}), skipped install (use --force to overwrite)`
+      );
+    }
+  }
+  for (const file of filesToWrite) {
+    writeFile(file.filePath, file.content);
+  }
+  if (config.theme) {
+    const absThemePath = path4.resolve(process.cwd(), config.theme);
+    const contextPath = path4.join(path4.dirname(absThemePath), "pdfx-theme-context.tsx");
+    if (!checkFileExists(contextPath)) {
+      ensureDir(path4.dirname(contextPath));
+      writeFile(contextPath, generateThemeContextFile());
+    }
+  }
+}
+async function add(components, options = {}) {
+  if (!components || components.length === 0) {
+    console.error(chalk.red("Error: Component name required"));
+    console.log(chalk.dim("Usage: npx pdfx-cli@latest add <component...>"));
+    console.log(chalk.dim("Example: npx pdfx-cli@latest add heading text table\n"));
+    process.exit(1);
+  }
+  const reactPdfCheck = validateReactPdfRenderer();
+  if (!reactPdfCheck.installed) {
+    console.error(chalk.red("\nError: @react-pdf/renderer is not installed\n"));
+    console.log(chalk.yellow("  PDFx components require @react-pdf/renderer to work.\n"));
+    console.log(chalk.cyan("  Run: npx pdfx-cli@latest init"));
+    console.log(chalk.dim("  or install manually: npm install @react-pdf/renderer\n"));
+    process.exit(1);
+  }
+  if (!reactPdfCheck.valid) {
+    console.log(
+      chalk.yellow(
+        `
+  \u26A0 Warning: ${reactPdfCheck.message}
+  ${chalk.dim("\u2192")} You may encounter compatibility issues
+`
+      )
+    );
+  }
+  const configPath = path4.join(process.cwd(), "pdfx.json");
+  if (!checkFileExists(configPath)) {
+    console.error(chalk.red("Error: pdfx.json not found"));
+    console.log(chalk.yellow("Run: npx pdfx-cli@latest init"));
+    process.exit(1);
+  }
+  let config;
+  try {
+    config = readConfig(configPath);
+    if (options.registry) {
+      config = { ...config, registry: options.registry };
+    }
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(chalk.red(error.message));
+      if (error.suggestion) console.log(chalk.yellow(`  Hint: ${error.suggestion}`));
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(chalk.red(message));
+    }
+    process.exit(1);
+  }
+  const force = options.force ?? false;
+  const failed = [];
+  let installedCount = 0;
+  const resolvedComponents = [];
+  const validNames = [];
+  for (const componentName of components) {
+    const nameResult = componentNameSchema.safeParse(componentName);
+    if (!nameResult.success) {
+      console.error(chalk.red(`Invalid component name: "${componentName}"`));
+      console.log(
+        chalk.dim('  Names must be lowercase alphanumeric with hyphens (e.g., "data-table")')
+      );
+      failed.push(componentName);
+      continue;
+    }
+    validNames.push(componentName);
+  }
+  for (const componentName of validNames) {
+    const spinner = ora(`Resolving ${componentName}...`).start();
+    try {
+      const component = await fetchComponent(componentName, config.registry);
+      resolvedComponents.push(component);
+      spinner.succeed(`Resolved ${componentName}`);
+    } catch (error) {
+      spinner.fail(`Failed to resolve ${componentName}`);
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(chalk.dim(`  ${message}`));
+      failed.push(componentName);
+    }
+  }
+  if (resolvedComponents.length > 0) {
+    try {
+      const requirements = collectComponentDependencies(resolvedComponents);
+      await ensureComponentDependencies(requirements, options);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(chalk.red(message));
+      if (error instanceof ValidationError && error.suggestion) {
+        console.log(chalk.yellow(`  Hint: ${error.suggestion}`));
+      }
+      process.exit(1);
+    }
+  }
+  for (const component of resolvedComponents) {
+    const spinner = ora(`Adding ${component.name}...`).start();
+    try {
+      await installComponent(component, config, force);
+      installedCount++;
+      spinner.succeed(`Added ${component.name}`);
+    } catch (error) {
+      let shouldMarkAsFailed = true;
+      if (error instanceof ValidationError && error.message.includes("already exists")) {
+        spinner.info(error.message);
+        shouldMarkAsFailed = false;
+      } else if (error instanceof NetworkError || error instanceof RegistryError || error instanceof ValidationError) {
+        spinner.fail(error.message);
+        if (error.suggestion) {
+          console.log(chalk.dim(`  Hint: ${error.suggestion}`));
+        }
+      } else {
+        spinner.fail(`Failed to add ${component.name}`);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.dim(`  ${message}`));
+      }
+      if (shouldMarkAsFailed) {
+        failed.push(component.name);
+      }
+    }
+  }
+  console.log();
+  if (failed.length > 0) {
+    console.log(chalk.yellow(`Failed to add: ${failed.join(", ")}`));
+  }
+  if (installedCount > 0) {
+    const resolvedDir = path4.resolve(process.cwd(), config.componentDir);
+    console.log(chalk.green("Done!"));
+    console.log(chalk.dim(`Components installed to: ${resolvedDir}
+`));
+  }
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+
+// src/commands/block.ts
+import path5 from "path";
+import chalk2 from "chalk";
+import ora2 from "ora";
+import prompts2 from "prompts";
+async function fetchBlock(name, registryUrl) {
+  const url = `${registryUrl}/${REGISTRY_SUBPATHS.BLOCKS}/${name}.json`;
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  } catch (err) {
+    const isTimeout = err instanceof Error && err.name === "TimeoutError";
+    throw new NetworkError(
+      isTimeout ? "Registry request timed out" : `Could not reach ${registryUrl}`
+    );
+  }
+  if (!response.ok) {
+    throw new RegistryError(
+      response.status === 404 ? `Block "${name}" not found in registry` : `Registry returned HTTP ${response.status}`,
+      response.status === 404 ? 'Run "npx pdfx-cli@latest block list" to see all available blocks' : void 0
+    );
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new RegistryError(`Invalid response for "${name}": not valid JSON`);
+  }
+  const result = registryItemSchema.safeParse(data);
+  if (!result.success) {
+    throw new RegistryError(
+      `Invalid registry entry for "${name}": ${result.error.issues[0]?.message}`
+    );
+  }
+  return result.data;
+}
+function resolveBlockImports(content, blockName, config) {
+  const cwd = process.cwd();
+  const blockSubdir = path5.resolve(cwd, config.blockDir ?? DEFAULTS.BLOCK_DIR, blockName);
+  let result = content.replace(
+    /from '\.\.\/\.\.\/components\/pdfx\/([a-z][a-z0-9-]*)\/pdfx-([a-z][a-z0-9-]*)'/g,
+    (_match, componentName) => {
+      const absCompFile = path5.resolve(
+        cwd,
+        config.componentDir,
+        componentName,
+        `pdfx-${componentName}`
+      );
+      let rel = path5.relative(blockSubdir, absCompFile);
+      if (!rel.startsWith(".")) rel = `./${rel}`;
+      return `from '${rel}'`;
+    }
+  );
+  if (config.theme) {
+    const absThemePath = path5.resolve(cwd, config.theme).replace(/\.tsx?$/, "");
+    let relTheme = path5.relative(blockSubdir, absThemePath);
+    if (!relTheme.startsWith(".")) relTheme = `./${relTheme}`;
+    const absContextPath = path5.join(
+      path5.dirname(path5.resolve(cwd, config.theme)),
+      "pdfx-theme-context"
+    );
+    let relContext = path5.relative(blockSubdir, absContextPath);
+    if (!relContext.startsWith(".")) relContext = `./${relContext}`;
+    result = result.replace(/from '\.\.\/\.\.\/lib\/pdfx-theme'/g, `from '${relTheme}'`);
+    result = result.replace(/from '\.\.\/\.\.\/lib\/pdfx-theme-context'/g, `from '${relContext}'`);
+  }
+  return result;
+}
+async function resolveConflict(fileName, currentDecision) {
+  if (currentDecision === "overwrite-all") return "overwrite-all";
+  const { action } = await prompts2({
+    type: "select",
+    name: "action",
+    message: `${chalk2.yellow(fileName)} already exists. What would you like to do?`,
+    choices: [
+      { title: "Skip", value: "skip", description: "Keep the existing file unchanged" },
+      { title: "Overwrite", value: "overwrite", description: "Replace this file only" },
+      {
+        title: "Overwrite all",
+        value: "overwrite-all",
+        description: "Replace all conflicting files"
+      }
+    ],
+    initial: 0
+  });
+  if (!action) throw new ValidationError("Cancelled by user");
+  return action;
+}
+async function ensurePeerComponents(block, config, force) {
+  const installedPeers = [];
+  const peerWarnings = [];
+  if (!block.peerComponents || block.peerComponents.length === 0) {
+    return { installedPeers, peerWarnings, allSkipped: false };
+  }
+  const componentBaseDir = path5.resolve(process.cwd(), config.componentDir);
+  for (const componentName of block.peerComponents) {
+    const componentDir = path5.join(componentBaseDir, componentName);
+    const expectedMain = path5.join(componentDir, `pdfx-${componentName}.tsx`);
+    if (checkFileExists(componentDir)) {
+      if (!checkFileExists(expectedMain)) {
+        peerWarnings.push(
+          `${componentName}: directory exists but expected file missing (${path5.basename(expectedMain)})`
+        );
+        continue;
+      }
+      if (!force) {
+        peerWarnings.push(
+          `${componentName}: already exists, skipped install (use "npx pdfx-cli@latest diff ${componentName}" to verify freshness)`
+        );
+        continue;
+      }
+    }
+    const component = await fetchComponent(componentName, config.registry);
+    ensureDir(componentDir);
+    const componentRelDir = path5.join(config.componentDir, component.name);
+    for (const file of component.files) {
+      const fileName = path5.basename(file.path);
+      const filePath = safePath(componentDir, fileName);
+      let content = file.content;
+      if (config.theme && (content.includes("pdfx-theme") || content.includes("pdfx-theme-context"))) {
+        content = resolveThemeImport(componentRelDir, config.theme, content);
+      }
+      writeFile(filePath, content);
+    }
+    installedPeers.push(componentName);
+  }
+  return { installedPeers, peerWarnings, allSkipped: false };
+}
+async function installBlock(name, config, force, spinner) {
+  const block = await fetchBlock(name, config.registry);
+  const peerResult = await ensurePeerComponents(block, config, force);
+  const blockBaseDir = path5.resolve(process.cwd(), config.blockDir ?? DEFAULTS.BLOCK_DIR);
+  const blockDir = path5.join(blockBaseDir, block.name);
+  ensureDir(blockDir);
+  const filesToWrite = [];
+  let allSkipped = false;
+  let globalDecision = null;
+  const resolved = [];
+  for (const file of block.files) {
+    const fileName = path5.basename(file.path);
+    const filePath = safePath(blockDir, fileName);
+    let content = file.content;
+    if (/\.(tsx?|jsx?)$/.test(fileName) && content.includes("../../")) {
+      content = resolveBlockImports(content, block.name, config);
+    }
+    filesToWrite.push({ filePath, content });
+  }
+  if (!force) {
+    const hasConflicts = filesToWrite.some((f) => checkFileExists(f.filePath));
+    if (hasConflicts) {
+      spinner.stop();
+    }
+    for (const file of filesToWrite) {
+      if (checkFileExists(file.filePath)) {
+        const decision = await resolveConflict(path5.basename(file.filePath), globalDecision);
+        if (decision === "overwrite-all") {
+          globalDecision = "overwrite-all";
+        }
+        resolved.push({ ...file, skip: decision === "skip" });
+      } else {
+        resolved.push({ ...file, skip: false });
+      }
+    }
+    allSkipped = resolved.every((f) => f.skip);
+    for (const file of resolved) {
+      if (!file.skip) {
+        writeFile(file.filePath, file.content);
+      } else {
+        console.log(chalk2.dim(`  skipped ${path5.basename(file.filePath)}`));
+      }
+    }
+  } else {
+    for (const file of filesToWrite) {
+      writeFile(file.filePath, file.content);
+    }
+  }
+  if (config.theme) {
+    const absThemePath = path5.resolve(process.cwd(), config.theme);
+    const contextPath = path5.join(path5.dirname(absThemePath), "pdfx-theme-context.tsx");
+    if (!checkFileExists(contextPath)) {
+      ensureDir(path5.dirname(contextPath));
+      writeFile(contextPath, generateThemeContextFile());
+    }
+  }
+  return { ...peerResult, allSkipped };
+}
+async function blockAdd(names, options = {}) {
+  const configPath = path5.join(process.cwd(), "pdfx.json");
+  let config;
+  const force = options.force ?? false;
+  const failed = [];
+  let installedCount = 0;
+  if (!checkFileExists(configPath)) {
+    console.error(chalk2.red("Error: pdfx.json not found"));
+    console.log(chalk2.yellow("Run: npx pdfx-cli@latest init"));
+    process.exit(1);
+  }
+  try {
+    config = readConfig(configPath);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(chalk2.red(error.message));
+      if (error.suggestion) console.log(chalk2.yellow(`  Hint: ${error.suggestion}`));
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(chalk2.red(message));
+    }
+    process.exit(1);
+  }
+  for (const blockName of names) {
+    const nameResult = componentNameSchema.safeParse(blockName);
+    if (!nameResult.success) {
+      console.error(chalk2.red(`Invalid block name: "${blockName}"`));
+      console.log(
+        chalk2.dim('  Names must be lowercase alphanumeric with hyphens (e.g., "invoice-classic")')
+      );
+      failed.push(blockName);
+      continue;
+    }
+    const spinner = ora2(`Adding block ${blockName}...`).start();
+    try {
+      const result = await installBlock(blockName, config, force, spinner);
+      if (result.allSkipped) {
+        spinner.info(
+          `Skipped ${chalk2.cyan(blockName)} \u2014 all files already exist (use ${chalk2.cyan("--force")} to overwrite)`
+        );
+      } else {
+        installedCount++;
+        spinner.succeed(`Added block ${chalk2.cyan(blockName)}`);
+        if (result.installedPeers.length > 0) {
+          console.log(
+            chalk2.green(`  Installed required components: ${result.installedPeers.join(", ")}`)
+          );
+        }
+        for (const warning of result.peerWarnings) {
+          console.log(chalk2.yellow(`  Warning: ${warning}`));
+        }
+      }
+    } catch (error) {
+      if (error instanceof ValidationError && error.message.includes("Cancelled")) {
+        spinner.info("Cancelled");
+        process.exit(0);
+      } else if (error instanceof NetworkError || error instanceof RegistryError || error instanceof ValidationError) {
+        spinner.fail(error.message);
+        if (error.suggestion) {
+          console.log(chalk2.dim(`  Hint: ${error.suggestion}`));
+        }
+      } else {
+        spinner.fail(`Failed to add block ${blockName}`);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk2.dim(`  ${message}`));
+      }
+      failed.push(blockName);
+    }
+  }
+  console.log();
+  if (failed.length > 0) {
+    console.log(chalk2.yellow(`Failed: ${failed.join(", ")}`));
+  }
+  if (installedCount > 0) {
+    const resolvedDir = path5.resolve(process.cwd(), config.blockDir ?? DEFAULTS.BLOCK_DIR);
+    console.log(chalk2.green("Done!"));
+    console.log(chalk2.dim(`Blocks installed to: ${resolvedDir}
+`));
+  }
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+async function blockList() {
+  const configPath = path5.join(process.cwd(), "pdfx.json");
+  if (!checkFileExists(configPath)) {
+    console.error(chalk2.red("Error: pdfx.json not found"));
+    console.log(chalk2.yellow("Run: npx pdfx-cli@latest init"));
+    process.exit(1);
+  }
+  let config;
+  try {
+    config = readConfig(configPath);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(chalk2.red(error.message));
+      if (error.suggestion) console.log(chalk2.yellow(`  Hint: ${error.suggestion}`));
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(chalk2.red(message));
+    }
+    process.exit(1);
+  }
+  const spinner = ora2("Fetching block list...").start();
+  try {
+    let response;
+    try {
+      response = await fetch(`${config.registry}/index.json`, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+      });
+    } catch (err) {
+      const isTimeout = err instanceof Error && err.name === "TimeoutError";
+      throw new NetworkError(
+        isTimeout ? "Registry request timed out" : `Could not reach ${config.registry}`
+      );
+    }
+    if (!response.ok) {
+      throw new RegistryError(`Registry returned HTTP ${response.status}`);
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new RegistryError("Invalid response from registry: not valid JSON");
+    }
+    const result = registrySchema.safeParse(data);
+    if (!result.success) {
+      throw new RegistryError("Invalid registry format");
+    }
+    spinner.stop();
+    const blocks = result.data.items.filter((item) => item.type === "registry:block");
+    if (blocks.length === 0) {
+      console.log(chalk2.dim("\n  No blocks available in the registry.\n"));
+      return;
+    }
+    const blockBaseDir = path5.resolve(process.cwd(), config.blockDir ?? DEFAULTS.BLOCK_DIR);
+    console.log(chalk2.bold(`
+  Available Blocks (${blocks.length})
+`));
+    for (const item of blocks) {
+      const blockDir = path5.join(blockBaseDir, item.name);
+      const installed = checkFileExists(blockDir);
+      const status = installed ? chalk2.green("[installed]") : chalk2.dim("[not installed]");
+      console.log(`  ${chalk2.cyan(item.name.padEnd(22))} ${item.description ?? ""}`);
+      console.log(`  ${"".padEnd(22)} ${status}`);
+      if (item.peerComponents && item.peerComponents.length > 0) {
+        console.log(chalk2.dim(`  ${"".padEnd(22)} requires: ${item.peerComponents.join(", ")}`));
+      }
+      console.log();
+    }
+    console.log(
+      chalk2.dim(`  Install with: ${chalk2.cyan("npx pdfx-cli@latest block add <block-name>")}
+`)
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    spinner.fail(message);
+    process.exit(1);
+  }
+}
+
+// src/commands/diff.ts
+import fs6 from "fs";
+import path6 from "path";
+import chalk3 from "chalk";
+import ora3 from "ora";
+async function diff(components) {
+  const configPath = path6.join(process.cwd(), "pdfx.json");
+  let hasFailures = false;
+  if (!checkFileExists(configPath)) {
+    console.error(chalk3.red("Error: pdfx.json not found"));
+    console.log(chalk3.yellow("Run: npx pdfx-cli@latest init"));
+    process.exit(1);
+  }
+  let config;
+  try {
+    config = readConfig(configPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk3.red(message));
+    process.exit(1);
+  }
+  const targetDir = path6.resolve(process.cwd(), config.componentDir);
+  for (const componentName of components) {
+    const nameResult = componentNameSchema.safeParse(componentName);
+    if (!nameResult.success) {
+      console.error(chalk3.red(`Invalid component name: "${componentName}"`));
+      hasFailures = true;
+      continue;
+    }
+    const spinner = ora3(`Comparing ${componentName}...`).start();
+    try {
+      const component = await fetchComponent(componentName, config.registry);
+      spinner.stop();
+      const componentSubDir = path6.join(targetDir, component.name);
+      for (const file of component.files) {
+        const fileName = path6.basename(file.path);
+        const localPath = safePath(componentSubDir, fileName);
+        if (!checkFileExists(localPath)) {
+          console.log(chalk3.yellow(`  ${fileName}: not installed locally`));
+          continue;
+        }
+        const localContent = fs6.readFileSync(localPath, "utf-8");
+        const registryContent = config.theme && (file.content.includes("pdfx-theme") || file.content.includes("pdfx-theme-context")) ? resolveThemeImport(
+          path6.join(config.componentDir, component.name),
+          config.theme,
+          file.content
+        ) : file.content;
+        if (localContent === registryContent) {
+          console.log(chalk3.green(`  ${fileName}: up to date`));
+        } else {
+          console.log(chalk3.yellow(`  ${fileName}: differs from registry`));
+          const localLines = localContent.split("\n");
+          const registryLines = registryContent.split("\n");
+          const lineDiff = localLines.length - registryLines.length;
+          console.log(chalk3.dim(`    Local: ${localLines.length} lines`));
+          console.log(chalk3.dim(`    Registry: ${registryLines.length} lines`));
+          if (lineDiff !== 0) {
+            const diffText = lineDiff > 0 ? `${Math.abs(lineDiff)} line${Math.abs(lineDiff) > 1 ? "s" : ""} added locally` : `${Math.abs(lineDiff)} line${Math.abs(lineDiff) > 1 ? "s" : ""} removed locally`;
+            console.log(chalk3.dim(`    \u2192 ${diffText}`));
+          }
+        }
+      }
+      console.log();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      spinner.fail(message);
+      hasFailures = true;
+    }
+  }
+  if (hasFailures) {
+    process.exit(1);
+  }
+}
+
+// src/commands/init.ts
+import fs7 from "fs";
+import path9 from "path";
+import chalk6 from "chalk";
+import ora5 from "ora";
+import prompts4 from "prompts";
+
+// src/utils/install-dependencies.ts
+import chalk4 from "chalk";
+import { execa as execa2 } from "execa";
+import ora4 from "ora";
+import prompts3 from "prompts";
+async function promptAndInstallReactPdf(validation, cwd = process.cwd()) {
+  if (validation.installed && validation.valid) {
+    return {
+      success: true,
+      message: "@react-pdf/renderer is already installed and compatible"
+    };
+  }
+  const packageRoot = findPackageRoot(cwd);
+  const pm = detectPackageManager(cwd);
+  const packageName = "@react-pdf/renderer";
+  const installCmd2 = getInstallCommand(pm.name, [packageName]);
+  console.log(chalk4.yellow("\n  \u26A0 @react-pdf/renderer is required but not installed\n"));
+  console.log(chalk4.dim(`    Package root: ${packageRoot}`));
+  console.log(chalk4.dim(`    This command will run: ${installCmd2}
+`));
+  const { shouldInstall } = await prompts3({
+    type: "confirm",
+    name: "shouldInstall",
+    message: "Install @react-pdf/renderer now?",
+    initial: true
+  });
+  if (!shouldInstall) {
+    return {
+      success: false,
+      message: `Installation cancelled. Please install manually:
+  ${chalk4.cyan(installCmd2)}`
+    };
+  }
+  const spinner = ora4("Installing @react-pdf/renderer...").start();
+  try {
+    const installArgs = pm.installCommand.split(" ").slice(1);
+    await execa2(pm.name, [...installArgs, packageName], {
+      cwd: packageRoot,
+      stdio: "pipe"
+    });
+    spinner.succeed("Installed @react-pdf/renderer");
+    return {
+      success: true,
+      message: "@react-pdf/renderer installed successfully"
+    };
+  } catch (error) {
+    spinner.fail("Failed to install @react-pdf/renderer");
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      message: `Installation failed: ${message}
+  Try manually: ${chalk4.cyan(installCmd2)}`
+    };
+  }
+}
+async function ensureReactPdfRenderer(validation, cwd = process.cwd()) {
+  if (!validation.installed) {
+    const result = await promptAndInstallReactPdf(validation, cwd);
+    if (!result.success) {
+      console.error(chalk4.red(`
+  ${result.message}
+`));
+      return false;
+    }
+    return true;
+  }
+  if (!validation.valid) {
+    console.log(
+      chalk4.yellow(
+        `
+  \u26A0 ${validation.message}
+  ${chalk4.dim("\u2192")} You may encounter compatibility issues
+`
+      )
+    );
+  }
+  return true;
+}
+
+// src/utils/pre-flight.ts
+import chalk5 from "chalk";
+
+// src/utils/environment-validator.ts
+import path7 from "path";
+function validatePackageJson(cwd = process.cwd()) {
+  const pkgPath = path7.join(cwd, "package.json");
+  const exists = checkFileExists(pkgPath);
+  return {
+    valid: exists,
+    message: exists ? "package.json found" : "No package.json found in current directory",
+    fixCommand: exists ? void 0 : 'Run "npm init" or "pnpm init" to create a package.json'
+  };
+}
+function validateReactProject(cwd = process.cwd()) {
+  const pkgPath = path7.join(cwd, "package.json");
+  if (!checkFileExists(pkgPath)) {
+    return {
+      valid: false,
+      message: "Cannot validate React project without package.json"
+    };
+  }
+  try {
+    const pkg = readJsonFile(pkgPath);
+    const deps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies
+    };
+    const hasReact = "react" in deps;
+    return {
+      valid: hasReact,
+      message: hasReact ? "React is installed" : "This does not appear to be a React project",
+      fixCommand: hasReact ? void 0 : "Install React: npx create-vite@latest or npx create-react-app"
+    };
+  } catch {
+    return {
+      valid: false,
+      message: "Failed to read package.json"
+    };
+  }
+}
+function validateEnvironment(cwd = process.cwd()) {
+  return {
+    hasPackageJson: validatePackageJson(cwd),
+    isReactProject: validateReactProject(cwd)
+  };
+}
+
+// src/utils/pre-flight.ts
+function runPreFlightChecks(cwd = process.cwd()) {
+  const environment = validateEnvironment(cwd);
+  const dependencies = validateDependencies(cwd);
+  const blockingErrors = [];
+  const warnings = [];
+  if (!environment.hasPackageJson.valid) {
+    blockingErrors.push(
+      `${environment.hasPackageJson.message}
+  ${chalk5.dim("\u2192")} ${environment.hasPackageJson.fixCommand}`
+    );
+  } else if (!environment.isReactProject.valid) {
+    blockingErrors.push(
+      `${environment.isReactProject.message}
+  ${chalk5.dim("\u2192")} ${environment.isReactProject.fixCommand}`
+    );
+  } else {
+    if (!dependencies.react.valid && dependencies.react.installed) {
+      warnings.push(
+        `${dependencies.react.message}
+  ${chalk5.dim("\u2192")} Current: ${dependencies.react.currentVersion}, Required: ${dependencies.react.requiredVersion}`
+      );
+    } else if (!dependencies.react.installed) {
+      blockingErrors.push(
+        `${dependencies.react.message}
+  ${chalk5.dim("\u2192")} Install React: npm install react react-dom`
+      );
+    }
+  }
+  if (!dependencies.nodeJs.valid) {
+    blockingErrors.push(
+      `${dependencies.nodeJs.message}
+  ${chalk5.dim("\u2192")} Current: ${dependencies.nodeJs.currentVersion}, Required: ${dependencies.nodeJs.requiredVersion}
+  ${chalk5.dim("\u2192")} Visit https://nodejs.org to upgrade`
+    );
+  }
+  if (dependencies.reactPdfRenderer.installed && !dependencies.reactPdfRenderer.valid) {
+    warnings.push(
+      `${dependencies.reactPdfRenderer.message}
+  ${chalk5.dim("\u2192")} Consider upgrading: npm install @react-pdf/renderer@latest`
+    );
+  }
+  return {
+    environment,
+    dependencies,
+    blockingErrors,
+    warnings,
+    canProceed: blockingErrors.length === 0
+  };
+}
+function displayPreFlightResults(result) {
+  console.log(chalk5.bold("\n  Pre-flight Checks:\n"));
+  if (result.blockingErrors.length > 0) {
+    console.log(chalk5.red("  \u2717 Blocking Issues:\n"));
+    for (const error of result.blockingErrors) {
+      console.log(chalk5.red(`    \u2022 ${error}
+`));
+    }
+  }
+  if (result.warnings.length > 0) {
+    console.log(chalk5.yellow("  \u26A0 Warnings:\n"));
+    for (const warning of result.warnings) {
+      console.log(chalk5.yellow(`    \u2022 ${warning}
+`));
+    }
+  }
+  if (result.blockingErrors.length === 0 && result.warnings.length === 0) {
+    console.log(chalk5.green("  \u2713 All checks passed!\n"));
+  }
+}
+
+// src/utils/theme-path.ts
+import path8 from "path";
+function normalizeThemePath(value) {
+  const trimmed = value.trim();
+  if (trimmed && !path8.isAbsolute(trimmed) && !trimmed.startsWith(".")) {
+    return `./${trimmed}`;
+  }
+  return trimmed;
+}
+function validateThemePath(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return "Theme path is required";
+  if (path8.isAbsolute(trimmed)) {
+    return "Please use a relative path (e.g., ./src/lib/pdfx-theme.ts)";
+  }
+  if (trimmed.startsWith(".") && !trimmed.startsWith("./") && !trimmed.startsWith("../")) {
+    return "Path must start with ./ or ../ (e.g., ./src/lib/pdfx-theme.ts)";
+  }
+  if (!trimmed.endsWith(".ts") && !trimmed.endsWith(".tsx")) {
+    return "Theme file must have a .ts or .tsx extension";
+  }
+  return true;
+}
+
+// src/commands/init.ts
+async function init(options = {}) {
+  console.log(chalk6.bold.cyan("\n  Welcome to the pdfx cli\n"));
+  const preFlightResult = runPreFlightChecks();
+  displayPreFlightResults(preFlightResult);
+  if (!preFlightResult.canProceed) {
+    console.error(
+      chalk6.red("\n  Cannot proceed due to blocking issues. Please fix them and try again.\n")
+    );
+    process.exit(1);
+  }
+  const hasReactPdf = await ensureReactPdfRenderer(preFlightResult.dependencies.reactPdfRenderer);
+  if (!hasReactPdf) {
+    console.error(
+      chalk6.red("\n  @react-pdf/renderer is required. Please install it and try again.\n")
+    );
+    process.exit(1);
+  }
+  const existingConfig = path9.join(process.cwd(), "pdfx.json");
+  if (fs7.existsSync(existingConfig)) {
+    if (options.yes) {
+      console.log(chalk6.dim("  pdfx.json already exists \u2014 overwriting (--yes)."));
+    } else {
+      const { overwrite } = await prompts4({
+        type: "confirm",
+        name: "overwrite",
+        message: "pdfx.json already exists. Overwrite?",
+        initial: false
+      });
+      if (!overwrite) {
+        console.log(chalk6.yellow("Init cancelled \u2014 existing config preserved."));
+        return;
+      }
+    }
+  }
+  const answers = options.yes ? {
+    componentDir: DEFAULTS.COMPONENT_DIR,
+    blockDir: DEFAULTS.BLOCK_DIR,
+    registry: DEFAULTS.REGISTRY_URL,
+    themePreset: "professional",
+    themePath: normalizeThemePath(DEFAULTS.THEME_FILE)
+  } : await prompts4(
+    [
+      {
+        type: "text",
+        name: "componentDir",
+        message: "Where should we install components?",
+        initial: DEFAULTS.COMPONENT_DIR,
+        validate: (value) => {
+          if (!value || value.trim().length === 0) {
+            return "Component directory is required";
+          }
+          if (path9.isAbsolute(value)) {
+            return "Please use a relative path (e.g., ./src/components/pdfx)";
+          }
+          if (!value.startsWith(".")) {
+            return "Path should start with ./ or ../ (e.g., ./src/components/pdfx)";
+          }
+          return true;
+        }
+      },
+      {
+        type: "text",
+        name: "blockDir",
+        message: "Where should we install blocks?",
+        initial: DEFAULTS.BLOCK_DIR,
+        validate: (value) => {
+          if (!value || value.trim().length === 0) {
+            return "Block directory is required";
+          }
+          if (path9.isAbsolute(value)) {
+            return "Please use a relative path (e.g., ./src/blocks/pdfx)";
+          }
+          if (!value.startsWith(".")) {
+            return "Path should start with ./ or ../ (e.g., ./src/blocks/pdfx)";
+          }
+          return true;
+        }
+      },
+      {
+        type: "text",
+        name: "registry",
+        message: "Registry URL:",
+        initial: DEFAULTS.REGISTRY_URL,
+        validate: (value) => {
+          if (!value || !value.startsWith("http")) {
+            return "Please enter a valid HTTP(S) URL";
+          }
+          return true;
+        }
+      },
+      {
+        type: "select",
+        name: "themePreset",
+        message: "Choose a theme:",
+        choices: [
+          {
+            title: "Professional",
+            description: "Serif headings, navy colors, generous margins",
+            value: "professional"
+          },
+          {
+            title: "Modern",
+            description: "Sans-serif, vibrant purple, tight spacing",
+            value: "modern"
+          },
+          {
+            title: "Minimal",
+            description: "Monospace headings, stark black, maximum whitespace",
+            value: "minimal"
+          }
+        ],
+        initial: 0
+      },
+      {
+        type: "text",
+        name: "themePath",
+        message: "Where should we create the theme file?",
+        initial: DEFAULTS.THEME_FILE,
+        format: normalizeThemePath,
+        validate: validateThemePath
+      }
+    ],
+    {
+      onCancel: () => {
+        console.log(chalk6.yellow("\nSetup cancelled."));
+        process.exit(0);
+      }
+    }
+  );
+  if (!answers.componentDir || !answers.registry) {
+    console.error(chalk6.red("Missing required fields. Run npx pdfx-cli@latest init again."));
+    process.exit(1);
+  }
+  const config = {
+    $schema: DEFAULTS.SCHEMA_URL,
+    componentDir: answers.componentDir,
+    registry: answers.registry,
+    theme: answers.themePath || DEFAULTS.THEME_FILE,
+    blockDir: answers.blockDir || DEFAULTS.BLOCK_DIR
+  };
+  const validation = configSchema.safeParse(config);
+  if (!validation.success) {
+    const issues = validation.error.issues.map((i) => {
+      const fieldPath = i.path.length > 0 ? i.path.join(".") : "root";
+      return `"${fieldPath}": ${i.message}`;
+    }).join("; ");
+    console.error(chalk6.red(`Invalid configuration: ${issues}`));
+    process.exit(1);
+  }
+  const spinner = ora5("Creating config and theme files...").start();
+  try {
+    const componentDirPath = path9.resolve(process.cwd(), answers.componentDir);
+    ensureDir(componentDirPath);
+    fs7.writeFileSync(path9.join(process.cwd(), "pdfx.json"), JSON.stringify(config, null, 2));
+    const presetName = answers.themePreset || "professional";
+    const preset = themePresets[presetName];
+    const themePath = path9.resolve(process.cwd(), config.theme);
+    ensureDir(path9.dirname(themePath));
+    fs7.writeFileSync(themePath, generateThemeFile(preset), "utf-8");
+    const contextPath = path9.join(path9.dirname(themePath), "pdfx-theme-context.tsx");
+    fs7.writeFileSync(contextPath, generateThemeContextFile(), "utf-8");
+    spinner.succeed(`Created pdfx.json + ${config.theme} (${presetName} theme)`);
+    console.log(chalk6.green("\nSuccess! You can now run:"));
+    console.log(chalk6.cyan("  npx pdfx-cli@latest add heading"));
+    console.log(chalk6.cyan("  npx pdfx-cli@latest block add invoice-classic"));
+    console.log(chalk6.dim(`
+  Components: ${path9.resolve(process.cwd(), answers.componentDir)}`));
+    console.log(chalk6.dim(`  Blocks: ${path9.resolve(process.cwd(), config.blockDir)}`));
+    console.log(chalk6.dim(`  Theme: ${path9.resolve(process.cwd(), config.theme)}
+`));
+  } catch (error) {
+    spinner.fail("Failed to create config");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk6.dim(`  ${message}`));
+    process.exit(1);
+  }
+}
+
+// src/commands/list.ts
+import path10 from "path";
+import chalk7 from "chalk";
+import ora6 from "ora";
+async function list() {
+  const configPath = path10.join(process.cwd(), "pdfx.json");
+  let config;
+  let hasLocalProject = false;
+  if (checkFileExists(configPath)) {
+    try {
+      config = readConfig(configPath);
+      hasLocalProject = true;
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        console.error(chalk7.red(error.message));
+        if (error.suggestion) console.log(chalk7.yellow(`  Hint: ${error.suggestion}`));
+      } else {
+        console.error(chalk7.red("Invalid pdfx.json"));
+      }
+      process.exit(1);
+    }
+  } else {
+    config = {
+      registry: DEFAULTS.REGISTRY_URL,
+      componentDir: DEFAULTS.COMPONENT_DIR,
+      theme: DEFAULTS.THEME_FILE,
+      blockDir: DEFAULTS.BLOCK_DIR
+    };
+    console.log(chalk7.dim("No pdfx.json found. Listing from default registry.\n"));
+  }
+  const spinner = ora6("Fetching registry...").start();
+  try {
+    let response;
+    try {
+      response = await fetch(`${config.registry}/index.json`, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+      });
+    } catch (err) {
+      const isTimeout = err instanceof Error && err.name === "TimeoutError";
+      throw new NetworkError(
+        isTimeout ? `Registry request timed out after 10 seconds.
+  ${chalk7.dim("Check your internet connection or try again later.")}` : `Could not reach registry at ${config.registry}
+  ${chalk7.dim("Verify the URL is correct and you have internet access.")}`
+      );
+    }
+    if (!response.ok) {
+      throw new RegistryError(`Registry returned HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    const result = registrySchema.safeParse(data);
+    if (!result.success) {
+      throw new RegistryError("Invalid registry format");
+    }
+    spinner.stop();
+    const components = result.data.items.filter((item) => item.type === "registry:ui");
+    const blocks = result.data.items.filter((item) => item.type === "registry:block");
+    const componentBaseDir = path10.resolve(process.cwd(), config.componentDir);
+    const blockBaseDir = path10.resolve(process.cwd(), config.blockDir ?? DEFAULTS.BLOCK_DIR);
+    console.log(chalk7.bold(`
+  Components (${components.length})`));
+    console.log(chalk7.dim("  Install with: npx pdfx-cli@latest add <component>\n"));
+    for (const item of components) {
+      const componentSubDir = path10.join(componentBaseDir, item.name);
+      const localPath = safePath(componentSubDir, `pdfx-${item.name}.tsx`);
+      const installed = hasLocalProject && checkFileExists(localPath);
+      const status = installed ? chalk7.green("[installed]") : chalk7.dim("[not installed]");
+      console.log(`  ${chalk7.cyan(item.name.padEnd(20))} ${item.description}`);
+      if (hasLocalProject) {
+        console.log(`  ${"".padEnd(20)} ${status}`);
+      }
+      console.log();
+    }
+    console.log(chalk7.bold(`  Blocks (${blocks.length})`));
+    console.log(
+      chalk7.dim("  Copy-paste designs. Install with: npx pdfx-cli@latest block add <block>\n")
+    );
+    for (const item of blocks) {
+      const blockDir = path10.join(blockBaseDir, item.name);
+      const installed = hasLocalProject && checkFileExists(blockDir);
+      const status = installed ? chalk7.green("[installed]") : chalk7.dim("[not installed]");
+      console.log(`  ${chalk7.cyan(item.name.padEnd(22))} ${item.description ?? ""}`);
+      if (hasLocalProject) {
+        console.log(`  ${"".padEnd(22)} ${status}`);
+      }
+      if (item.peerComponents && item.peerComponents.length > 0) {
+        console.log(chalk7.dim(`  ${"".padEnd(22)} requires: ${item.peerComponents.join(", ")}`));
+      }
+      console.log();
+    }
+    console.log(chalk7.dim("  Quick Start:"));
+    console.log(
+      chalk7.dim(
+        `    npx pdfx-cli@latest add heading table          ${chalk7.dim("# Add components")}`
+      )
+    );
+    console.log(
+      chalk7.dim(`    npx pdfx-cli@latest block add invoice-classic ${chalk7.dim("# Add a block")}`)
+    );
+    console.log();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    spinner.fail(message);
+    process.exit(1);
+  }
+}
+
+// src/commands/mcp.ts
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile as writeFile2 } from "fs/promises";
+import path11 from "path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Command } from "commander";
+import prompts5 from "prompts";
+
+// src/mcp/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z as z8 } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// src/mcp/tools/add-command.ts
+import dedent from "dedent";
+import { z as z2 } from "zod";
+
+// src/mcp/utils.ts
+var REGISTRY_BASE = DEFAULTS.REGISTRY_URL;
+var BLOCKS_BASE = `${DEFAULTS.REGISTRY_URL}/${REGISTRY_SUBPATHS.BLOCKS}`;
+async function fetchRegistryIndex() {
+  let response;
+  try {
+    response = await fetch(`${REGISTRY_BASE}/index.json`, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    const isTimeout = err instanceof Error && err.name === "TimeoutError";
+    throw new NetworkError(
+      isTimeout ? "Registry request timed out. Check your internet connection." : "Could not reach the PDFx registry. Check your internet connection."
+    );
+  }
+  if (!response.ok) {
+    throw new RegistryError(`Registry returned HTTP ${response.status}`);
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new RegistryError("Registry returned invalid JSON");
+  }
+  const result = registrySchema.safeParse(data);
+  if (!result.success) {
+    throw new RegistryError("Registry index has an unexpected format");
+  }
+  return result.data.items;
+}
+async function fetchRegistryItem(name, base = REGISTRY_BASE) {
+  const url = `${base}/${name}.json`;
+  let response;
+  try {
+    response = await fetch(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    const isTimeout = err instanceof Error && err.name === "TimeoutError";
+    throw new NetworkError(
+      isTimeout ? `Registry request timed out for "${name}".` : "Could not reach the PDFx registry. Check your internet connection."
+    );
+  }
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new RegistryError(
+        `"${name}" not found in the registry. Use list_components or list_blocks to see available items.`
+      );
+    }
+    throw new RegistryError(`Registry returned HTTP ${response.status} for "${name}"`);
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new RegistryError(`Registry returned invalid JSON for "${name}"`);
+  }
+  const result = registryItemSchema.safeParse(data);
+  if (!result.success) {
+    throw new RegistryError(`Unexpected registry format for "${name}"`);
+  }
+  return result.data;
+}
+function textResponse(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResponse(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true
+  };
+}
+
+// src/mcp/tools/add-command.ts
+var getAddCommandSchema = z2.object({
+  items: z2.array(z2.string().min(1)).min(1).describe(
+    "Item names to add, e.g. ['table', 'heading'] for components or ['invoice-modern'] for blocks"
+  ),
+  type: z2.enum(["component", "block"]).describe("Whether the items are components or blocks")
+});
+async function getAddCommand(args) {
+  const isBlock = args.type === "block";
+  const cmd = isBlock ? `npx pdfx-cli block add ${args.items.join(" ")}` : `npx pdfx-cli add ${args.items.join(" ")}`;
+  const installDir = isBlock ? "src/blocks/pdfx/" : "src/components/pdfx/";
+  const inspectTool = isBlock ? "get_block" : "get_component";
+  const itemList = args.items.map((i) => `- \`${i}\``).join("\n");
+  return textResponse(dedent`
+    # Add Command
+
+    \`\`\`bash
+    ${cmd}
+    \`\`\`
+
+    **Items:**
+    ${itemList}
+
+    **What this does:**
+    - Copies source files into \`${installDir}\`
+    - You own the code — no runtime package is added
+    ${isBlock ? "- The block includes a complete document layout ready to customize" : "- Each component gets its own subdirectory inside componentDir"}
+
+    **Before running:** make sure \`pdfx.json\` exists. Run \`npx pdfx-cli init\` if not.
+
+    **See source first:** call \`${inspectTool}\` with the item name to review the code before adding.
+
+    **After adding:** call \`get_audit_checklist\` to verify your setup is correct.
+  `);
+}
+
+// src/mcp/tools/audit.ts
+import dedent2 from "dedent";
+async function getAuditChecklist() {
+  return textResponse(dedent2`
+    # PDFx Setup Audit Checklist
+
+    Work through this after adding components or generating PDF document code.
+
+    ## Configuration
+    - [ ] \`pdfx.json\` exists in the project root
+    - [ ] \`componentDir\` path in \`pdfx.json\` is correct (default: \`./src/components/pdfx\`)
+    - [ ] Theme file exists at the path set in \`pdfx.json\` (default: \`./src/lib/pdfx-theme.ts\`)
+
+    ## Dependencies
+    - [ ] \`@react-pdf/renderer\` is installed — run \`npm ls @react-pdf/renderer\` to confirm
+    - [ ] Version is ≥ 3.0.0 (PDFx requires react-pdf v3+)
+
+    ## Imports
+    - [ ] PDFx components use **named exports**: \`import { Table, Heading } from '@/components/pdfx/...'\`
+    - [ ] \`Document\` and \`Page\` are imported from \`@react-pdf/renderer\`, not from PDFx
+    - [ ] No Tailwind classes, CSS variables, or DOM APIs are used inside PDF components
+    - [ ] All styles use \`StyleSheet.create({})\` from \`@react-pdf/renderer\`
+
+    ## Rendering
+    - [ ] The root PDF component is **not** inside a React Server Component
+    - [ ] Using \`renderToBuffer\`, \`PDFViewer\`, or \`PDFDownloadLink\` to render the document
+    - [ ] Root component returns \`<Document><Page>...</Page></Document>\`
+    - [ ] No console errors about missing fonts
+
+    ## TypeScript
+    - [ ] No TypeScript errors in component files
+    - [ ] Theme is typed as \`PdfxTheme\` (imported as a type from \`@pdfx/shared\`)
+
+    ---
+
+    ## Common Issues & Fixes
+
+    ### "Cannot find module @/components/pdfx/..."
+    The component hasn't been added yet. Run:
+    \`\`\`bash
+    npx pdfx-cli add <component-name>
+    \`\`\`
+
+    ### "Invalid hook call"
+    PDFx components render to PDF, not to the DOM — React hooks are not supported inside them.
+    Move hook calls to the parent component and pass data down as props.
+
+    ### "Text strings must be rendered inside \`<Text>\` component"
+    Wrap all string literals in \`<Text>\` from \`@react-pdf/renderer\`:
+    \`\`\`tsx
+    import { Text } from '@react-pdf/renderer';
+    // ✗ Wrong: <View>Hello</View>
+    // ✓ Correct: <View><Text>Hello</Text></View>
+    \`\`\`
+
+    ### Fonts not loading / rendering as a fallback
+    Register custom fonts in your theme file:
+    \`\`\`tsx
+    import { Font } from '@react-pdf/renderer';
+
+    Font.register({
+      family: 'Inter',
+      src: 'https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2',
+    });
+    \`\`\`
+
+    ### PDF renders blank or empty
+    Ensure your root component returns a \`<Document>\` with at least one \`<Page>\` inside:
+    \`\`\`tsx
+    import { Document, Page } from '@react-pdf/renderer';
+
+    export function MyDocument() {
+      return (
+        <Document>
+          <Page size="A4">
+            {/* content here */}
+          </Page>
+        </Document>
+      );
+    }
+    \`\`\`
+
+    ### @react-pdf/renderer TypeScript errors
+    Install the types package:
+    \`\`\`bash
+    npm install --save-dev @react-pdf/types
+    \`\`\`
+
+    ---
+
+    ## @react-pdf/renderer Layout Constraints
+
+    These are **fundamental PDF rendering limitations** — they cannot be fixed with CSS-like
+    style tweaks. Understanding them will save hours of debugging.
+
+    ### ⚠️ CRITICAL: Do NOT mix \`<View>\` and \`<Text>\` in the same flex row
+
+    In HTML, inline elements (spans, badges) can sit next to block text freely.
+    In \`@react-pdf/renderer\`, \`View\` and \`Text\` are fundamentally different node types.
+    Placing a \`View\`-based component (e.g. \`<Badge>\`, \`<PdfAlert>\`) **inline** alongside
+    a \`<Text>\` node in the same flex row causes irrecoverable misalignment, overlap, and
+    overflow that no amount of padding, margin, or \`alignItems\` can fix.
+
+    **Wrong — will cause layout corruption:**
+    \`\`\`tsx
+    {/* Badge is a View; Text is a Text node — they CANNOT share a flex row */}
+    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 6 }}>
+      <Text>INV-2026-001</Text>
+      <Badge label="PAID" variant="success" />
+    </View>
+    \`\`\`
+
+    **Correct — place View-based components on their own line:**
+    \`\`\`tsx
+    <View style={{ flexDirection: 'column', gap: 2 }}>
+      <Text>INV-2026-001</Text>
+      <Badge label="PAID" variant="success" />
+    </View>
+    \`\`\`
+
+    PDFx components that are \`View\`-based (cannot be mixed inline with \`<Text>\`):
+    \`Badge\`, \`PdfAlert\`, \`Card\`, \`Divider\`, \`KeyValue\`, \`Section\`, \`Table\`, \`DataTable\`,
+    \`PdfGraph\`, \`PdfImage\`, \`PdfSignatureBlock\`, \`PdfList\`
+
+    ### No \`position: absolute\` stacking inside \`<Text>\` nodes
+    Absolute positioning works on \`View\` elements but not inside \`Text\` runs.
+
+    ### \`gap\` only works between \`View\` siblings
+    Use \`gap\` on a \`View\` container whose children are all \`View\` elements.
+    If any child is a raw \`Text\` node, use \`marginBottom\` on siblings instead.
+
+    ### No percentage-based font sizes
+    \`@react-pdf/renderer\` requires numeric pt/px values for \`fontSize\`. Do not use strings like \`"1rem"\` or \`"120%"\`.
+  `);
+}
+
+// src/mcp/tools/blocks.ts
+import dedent3 from "dedent";
+import { z as z3 } from "zod";
+var listBlocksSchema = z3.object({});
+async function listBlocks() {
+  const items = await fetchRegistryIndex();
+  const blocks = items.filter((i) => i.type === "registry:block");
+  const invoices = blocks.filter((b) => b.name.startsWith("invoice-"));
+  const reports = blocks.filter((b) => b.name.startsWith("report-"));
+  const others = blocks.filter(
+    (b) => !b.name.startsWith("invoice-") && !b.name.startsWith("report-")
+  );
+  const formatBlock = (b) => {
+    const peers = b.peerComponents?.length ? ` _(requires: ${b.peerComponents.join(", ")})_` : "";
+    return `- **${b.name}** \u2014 ${b.description ?? "No description"}${peers}`;
+  };
+  const sections = [];
+  if (invoices.length > 0) {
+    sections.push(
+      `### Invoice Blocks (${invoices.length})
+${invoices.map(formatBlock).join("\n")}`
+    );
+  }
+  if (reports.length > 0) {
+    sections.push(`### Report Blocks (${reports.length})
+${reports.map(formatBlock).join("\n")}`);
+  }
+  if (others.length > 0) {
+    sections.push(`### Other Blocks (${others.length})
+${others.map(formatBlock).join("\n")}`);
+  }
+  return textResponse(dedent3`
+    # PDFx Blocks (${blocks.length})
+
+    Blocks are complete, copy-paste ready document layouts. Unlike components, they are full documents ready to customize.
+
+    ${sections.join("\n\n")}
+
+    ---
+    Add a block: \`npx pdfx-cli block add <name>\`
+    See full source: call \`get_block\` with the block name
+  `);
+}
+var getBlockSchema = z3.object({
+  block: z3.string().min(1).describe("Block name, e.g. 'invoice-modern', 'report-financial'")
+});
+async function getBlock(args) {
+  const item = await fetchRegistryItem(args.block, BLOCKS_BASE);
+  const fileList = item.files.map((f) => `- \`${f.path}\``).join("\n");
+  const peers = item.peerComponents?.length ? item.peerComponents.join(", ") : "none";
+  const fileSources = item.files.map(
+    (f) => dedent3`
+        ### \`${f.path}\`
+        \`\`\`tsx
+        ${f.content}
+        \`\`\`
+      `
+  ).join("\n\n");
+  return textResponse(dedent3`
+    # ${item.title ?? item.name}
+
+    ${item.description ?? ""}
+
+    ## Files
+    ${fileList}
+
+    ## Required PDFx Components
+    ${peers}
+
+    ## Add Command
+    \`\`\`bash
+    npx pdfx-cli block add ${args.block}
+    \`\`\`
+
+    ## Source Code
+    ${fileSources}
+  `);
+}
+
+// src/mcp/tools/components.ts
+import dedent4 from "dedent";
+import { z as z4 } from "zod";
+var listComponentsSchema = z4.object({});
+async function listComponents() {
+  const items = await fetchRegistryIndex();
+  const components = items.filter((i) => i.type === "registry:ui");
+  const rows = components.map((c) => `- **${c.name}** \u2014 ${c.description ?? "No description"}`).join("\n");
+  return textResponse(dedent4`
+    # PDFx Components (${components.length})
+
+    ${rows}
+
+    ---
+    Add a component: \`npx pdfx-cli add <name>\`
+    See full source, props, and exact export name: call \`get_component\` with the component name
+  `);
+}
+var getComponentSchema = z4.object({
+  component: z4.string().min(1).describe("Component name, e.g. 'table', 'heading', 'data-table'")
+});
+async function getComponent(args) {
+  const item = await fetchRegistryItem(args.component);
+  const fileList = item.files.map((f) => `- \`${f.path}\``).join("\n");
+  const deps = item.dependencies?.length ? item.dependencies.join(", ") : "none";
+  const devDeps = item.devDependencies?.length ? item.devDependencies.join(", ") : "none";
+  const registryDeps = item.registryDependencies?.length ? item.registryDependencies.join(", ") : "none";
+  const primaryContent = item.files[0]?.content ?? "";
+  const primaryPath = item.files[0]?.path ?? "";
+  const exportNames = extractAllExportNames(primaryContent);
+  const mainExport = extractExportName(primaryContent);
+  const exportSection = exportNames.length > 0 ? dedent4`
+          ## Exports
+          **Main component export:** \`${mainExport ?? exportNames[0]}\`
+
+          All named exports from \`${primaryPath}\`:
+          ${exportNames.map((n) => `- \`${n}\``).join("\n")}
+
+          **Import after \`npx pdfx-cli@latest add ${args.component}\`:**
+          \`\`\`tsx
+          import { ${mainExport ?? exportNames[0]} } from './components/pdfx/${args.component}/pdfx-${args.component}';
+          \`\`\`
+        ` : "";
+  const fileSources = item.files.map(
+    (f) => dedent4`
+        ### \`${f.path}\`
+        \`\`\`tsx
+        ${f.content}
+        \`\`\`
+      `
+  ).join("\n\n");
+  return textResponse(dedent4`
+    # ${item.title ?? item.name}
+
+    ${item.description ?? ""}
+
+    ## Files
+    ${fileList}
+
+    ## Dependencies
+    - Runtime: ${deps}
+    - Dev: ${devDeps}
+    - Other PDFx components required: ${registryDeps}
+
+    ${exportSection}
+
+    ## Add Command
+    \`\`\`bash
+    npx pdfx-cli add ${args.component}
+    \`\`\`
+
+    ## Source Code
+    ${fileSources}
+  `);
+}
+function extractExportName(source) {
+  if (!source) return null;
+  const matches = [...source.matchAll(/export\s+(?:function|const)\s+([A-Z][A-Za-z0-9]*)/g)];
+  if (matches.length === 0) return null;
+  return matches[0][1] ?? null;
+}
+function extractAllExportNames(source) {
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const m of source.matchAll(/export\s+(?:function|const|class)\s+([A-Za-z][A-Za-z0-9]*)/g)) {
+    const name = m[1];
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      results.push(name);
+    }
+  }
+  for (const m of source.matchAll(/export\s+\{([^}]+)\}/g)) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (name && /^[A-Za-z]/.test(name) && !seen.has(name)) {
+        seen.add(name);
+        results.push(name);
+      }
+    }
+  }
+  return results;
+}
+
+// src/mcp/tools/installation.ts
+import dedent5 from "dedent";
+import { z as z5 } from "zod";
+var getInstallationSchema = z5.object({
+  framework: z5.enum(["nextjs", "react", "vite", "remix", "other"]).describe("Target framework"),
+  package_manager: z5.enum(["npm", "pnpm", "yarn", "bun"]).describe("Package manager to use")
+});
+function installCmd(pm, pkg, dev = false) {
+  const base = { npm: "npm install", pnpm: "pnpm add", yarn: "yarn add", bun: "bun add" }[pm];
+  const devFlag = { npm: "--save-dev", pnpm: "-D", yarn: "--dev", bun: "-d" }[pm];
+  return dev ? `${base} ${devFlag} ${pkg}` : `${base} ${pkg}`;
+}
+var FRAMEWORK_NOTES = {
+  nextjs: dedent5`
+    ## Next.js Notes
+
+    **App Router** — Use a Route Handler to serve PDFs:
+    \`\`\`tsx
+    // app/api/pdf/route.ts
+    import { renderToBuffer } from '@react-pdf/renderer';
+    import { MyDocument } from '@/components/pdfx/my-document';
+
+    export async function GET() {
+      const buffer = await renderToBuffer(<MyDocument />);
+      return new Response(buffer, {
+        headers: { 'Content-Type': 'application/pdf' },
+      });
+    }
+    \`\`\`
+
+    **Important:** Do NOT render PDFx components inside React Server Components.
+    Always use a \`'use client'\` boundary or a Route Handler.
+
+    **Pages Router** — Use an API route:
+    \`\`\`tsx
+    // pages/api/pdf.ts
+    import type { NextApiRequest, NextApiResponse } from 'next';
+    import { renderToBuffer } from '@react-pdf/renderer';
+    import { MyDocument } from '@/components/pdfx/my-document';
+
+    export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+      const buffer = await renderToBuffer(<MyDocument />);
+      res.setHeader('Content-Type', 'application/pdf');
+      res.send(buffer);
+    }
+    \`\`\`
+  `,
+  react: dedent5`
+    ## React Notes
+
+    Display a PDF inline with \`PDFViewer\`:
+    \`\`\`tsx
+    import { PDFViewer } from '@react-pdf/renderer';
+    import { MyDocument } from './components/pdfx/my-document';
+
+    export function App() {
+      return (
+        <PDFViewer width="100%" height="600px">
+          <MyDocument />
+        </PDFViewer>
+      );
+    }
+    \`\`\`
+
+    Trigger a download with \`PDFDownloadLink\`:
+    \`\`\`tsx
+    import { PDFDownloadLink } from '@react-pdf/renderer';
+    import { MyDocument } from './components/pdfx/my-document';
+
+    export function DownloadButton() {
+      return (
+        <PDFDownloadLink document={<MyDocument />} fileName="document.pdf">
+          {({ loading }) => (loading ? 'Generating PDF...' : 'Download PDF')}
+        </PDFDownloadLink>
+      );
+    }
+    \`\`\`
+  `,
+  vite: dedent5`
+    ## Vite Notes
+
+    Works with both \`vite + react\` and \`vite + react-swc\` templates.
+
+    For client-side rendering, use \`PDFViewer\` or \`PDFDownloadLink\` from \`@react-pdf/renderer\`.
+
+    For server-side generation, use a separate Node.js server or Vite's server-side features.
+  `,
+  remix: dedent5`
+    ## Remix Notes
+
+    Use a resource route to serve PDFs:
+    \`\`\`tsx
+    // app/routes/pdf.tsx
+    import { renderToStream } from '@react-pdf/renderer';
+    import { MyDocument } from '~/components/pdfx/my-document';
+
+    export async function loader() {
+      const stream = await renderToStream(<MyDocument />);
+      return new Response(stream as unknown as ReadableStream, {
+        headers: { 'Content-Type': 'application/pdf' },
+      });
+    }
+    \`\`\`
+  `,
+  other: dedent5`
+    ## General Notes
+
+    \`@react-pdf/renderer\` works in any Node.js ≥ 18 environment.
+
+    - **Buffer output**: \`await renderToBuffer(<MyDocument />)\`
+    - **Stream output**: \`await renderToStream(<MyDocument />)\`
+    - **Client-side**: Use \`PDFViewer\` or \`PDFDownloadLink\` from \`@react-pdf/renderer\`
+  `
+};
+async function getInstallation(args) {
+  const pm = args.package_manager;
+  const fw = args.framework;
+  return textResponse(dedent5`
+    # PDFx Setup Guide: ${fw} + ${pm}
+
+    ## Step 1 — Install the peer dependency
+
+    \`\`\`bash
+    ${installCmd(pm, "@react-pdf/renderer")}
+    \`\`\`
+
+    ## Step 2 — Initialize PDFx in your project
+
+    \`\`\`bash
+    npx pdfx-cli init
+    \`\`\`
+
+    This creates \`pdfx.json\` in your project root and generates a theme file at \`src/lib/pdfx-theme.ts\`.
+
+    ## Step 3 — Add your first component
+
+    \`\`\`bash
+    npx pdfx-cli add heading text table
+    \`\`\`
+
+    Components are copied into \`src/components/pdfx/\`. You own the source — there is no runtime package dependency.
+
+    ## Step 4 — Or start with a complete document block
+
+    \`\`\`bash
+    npx pdfx-cli block add invoice-modern
+    \`\`\`
+
+    ${FRAMEWORK_NOTES[fw]}
+
+    ## Generated pdfx.json
+
+    \`\`\`json
+    {
+      "$schema": "https://pdfx.akashpise.dev/schema.json",
+      "componentDir": "./src/components/pdfx",
+      "blockDir": "./src/blocks/pdfx",
+      "registry": "https://pdfx.akashpise.dev/r",
+      "theme": "./src/lib/pdfx-theme.ts"
+    }
+    \`\`\`
+
+    ## pdfx.json Field Reference
+
+    All four fields are **required**. Relative paths must start with \`./\` or \`../\`.
+
+    | Field | Type | Description | Default |
+    |-------|------|-------------|---------|
+    | \`componentDir\` | string | Where individual components are installed | \`./src/components/pdfx\` |
+    | \`blockDir\` | string | Where full document blocks are installed | \`./src/blocks/pdfx\` |
+    | \`registry\` | string (URL) | Registry base URL (must start with http) | \`https://pdfx.akashpise.dev/r\` |
+    | \`theme\` | string | Path to your generated theme file | \`./src/lib/pdfx-theme.ts\` |
+
+    > **Non-interactive init (CI / AI agents):** pass \`--yes\` to accept all defaults:
+    > \`\`\`bash
+    > npx pdfx-cli init --yes
+    > \`\`\`
+
+    ## Troubleshooting
+
+    | Problem | Fix |
+    |---------|-----|
+    | TypeScript errors on \`@react-pdf/renderer\` | \`${installCmd(pm, "@react-pdf/types", true)}\` |
+    | "Cannot find module @/components/pdfx/..." | Run \`npx pdfx-cli@latest add <component>\` to install it |
+    | PDF renders blank | Ensure root returns \`<Document><Page>...</Page></Document>\` |
+    | "Invalid hook call" | PDFx components cannot use React hooks — pass data as props |
+
+    ---
+    Next: call \`get_audit_checklist\` to verify your setup is correct.
+  `);
+}
+
+// src/mcp/tools/search.ts
+import dedent6 from "dedent";
+import { z as z6 } from "zod";
+var searchRegistrySchema = z6.object({
+  query: z6.string().min(1).describe("Search query \u2014 matched against component name, title, and description"),
+  type: z6.enum(["all", "component", "block"]).optional().default("all").describe("Filter by item type (default: all)"),
+  limit: z6.number().int().positive().max(50).optional().default(20).describe("Maximum number of results to return (default: 20, max: 50)")
+});
+async function searchRegistry(args) {
+  const items = await fetchRegistryIndex();
+  const q = args.query.toLowerCase();
+  let pool = items;
+  if (args.type === "component") {
+    pool = items.filter((i) => i.type === "registry:ui");
+  } else if (args.type === "block") {
+    pool = items.filter((i) => i.type === "registry:block");
+  }
+  const scored = pool.map((item) => {
+    const name = item.name.toLowerCase();
+    const title = (item.title ?? "").toLowerCase();
+    const desc = (item.description ?? "").toLowerCase();
+    let score = 0;
+    if (name === q) score = 100;
+    else if (name.startsWith(q)) score = 80;
+    else if (name.includes(q)) score = 60;
+    else if (title.includes(q)) score = 40;
+    else if (desc.includes(q)) score = 20;
+    return { item, score };
+  }).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, args.limit);
+  if (scored.length === 0) {
+    return textResponse(dedent6`
+      # Search: "${args.query}"
+
+      No results found. Try a broader query or browse all items:
+      - \`list_components\` — see all 24 components
+      - \`list_blocks\` — see all 10 blocks
+    `);
+  }
+  const rows = scored.map(({ item }) => {
+    const typeLabel2 = item.type === "registry:ui" ? "component" : "block";
+    const addCmd = item.type === "registry:ui" ? `npx pdfx-cli add ${item.name}` : `npx pdfx-cli block add ${item.name}`;
+    return dedent6`
+      - **${item.name}** _(${typeLabel2})_ — ${item.description ?? "No description"}
+        \`${addCmd}\`
+    `;
+  });
+  const typeLabel = args.type === "all" ? "components + blocks" : args.type === "component" ? "components" : "blocks";
+  return textResponse(dedent6`
+    # Search: "${args.query}" — ${scored.length} result${scored.length === 1 ? "" : "s"} (${typeLabel})
+
+    ${rows.join("\n")}
+  `);
+}
+
+// src/mcp/tools/theme.ts
+import dedent7 from "dedent";
+import { z as z7 } from "zod";
+var getThemeSchema = z7.object({
+  theme: z7.enum(["professional", "modern", "minimal"]).describe("Theme preset name")
+});
+async function getTheme(args) {
+  const preset = themePresets[args.theme];
+  const { colors, typography, spacing, page } = preset;
+  return textResponse(dedent7`
+    # PDFx Theme: ${args.theme}
+
+    ## Colors
+    | Token | Value |
+    |-------|-------|
+    | foreground | \`${colors.foreground}\` |
+    | background | \`${colors.background}\` |
+    | primary | \`${colors.primary}\` |
+    | primaryForeground | \`${colors.primaryForeground}\` |
+    | accent | \`${colors.accent}\` |
+    | muted | \`${colors.muted}\` |
+    | mutedForeground | \`${colors.mutedForeground}\` |
+    | border | \`${colors.border}\` |
+    | destructive | \`${colors.destructive}\` |
+    | success | \`${colors.success}\` |
+    | warning | \`${colors.warning}\` |
+    | info | \`${colors.info}\` |
+
+    ## Typography
+
+    ### Body
+    - Font family: \`${typography.body.fontFamily}\`
+    - Font size: ${typography.body.fontSize}pt
+    - Line height: ${typography.body.lineHeight}
+
+    ### Headings
+    - Font family: \`${typography.heading.fontFamily}\`
+    - Font weight: ${typography.heading.fontWeight}
+    - Line height: ${typography.heading.lineHeight}
+    - h1: ${typography.heading.fontSize.h1}pt
+    - h2: ${typography.heading.fontSize.h2}pt
+    - h3: ${typography.heading.fontSize.h3}pt
+    - h4: ${typography.heading.fontSize.h4}pt
+    - h5: ${typography.heading.fontSize.h5}pt
+    - h6: ${typography.heading.fontSize.h6}pt
+
+    ## Spacing
+    - Page margins: top=${spacing.page.marginTop}pt · right=${spacing.page.marginRight}pt · bottom=${spacing.page.marginBottom}pt · left=${spacing.page.marginLeft}pt
+    - Section gap: ${spacing.sectionGap}pt
+    - Paragraph gap: ${spacing.paragraphGap}pt
+    - Component gap: ${spacing.componentGap}pt
+
+    ## Page
+    - Size: ${page.size}
+    - Orientation: ${page.orientation}
+
+    ## Apply This Theme
+    \`\`\`bash
+    npx pdfx-cli theme switch ${args.theme}
+    \`\`\`
+
+    ## Usage in Components
+    \`\`\`tsx
+    // Access theme values in a PDFx component
+    import type { PdfxTheme } from '@pdfx/shared';
+
+    interface Props {
+      theme: PdfxTheme;
+    }
+
+    export function MyComponent({ theme }: Props) {
+      return (
+        <View style={{ backgroundColor: theme.colors.background }}>
+          <Text style={{ color: theme.colors.foreground, fontSize: theme.typography.body.fontSize }}>
+            Content
+          </Text>
+        </View>
+      );
+    }
+    \`\`\`
+  `);
+}
+
+// src/mcp/index.ts
+var server = new Server(
+  { name: "pdfx", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "list_components",
+      description: "List all available PDFx PDF components with names and descriptions. Call this first to discover what components exist before adding any.",
+      inputSchema: zodToJsonSchema(listComponentsSchema)
+    },
+    {
+      name: "get_component",
+      description: "Get the full source code, files, and dependencies for a specific PDFx component. Use this to understand the API and props before using it in generated code.",
+      inputSchema: zodToJsonSchema(getComponentSchema)
+    },
+    {
+      name: "list_blocks",
+      description: "List all PDFx pre-built document blocks (complete invoice and report layouts ready to customize).",
+      inputSchema: zodToJsonSchema(listBlocksSchema)
+    },
+    {
+      name: "get_block",
+      description: "Get the full source code for a PDFx document block. Returns the complete layout code ready to customize for your use case.",
+      inputSchema: zodToJsonSchema(getBlockSchema)
+    },
+    {
+      name: "search_registry",
+      description: "Search PDFx components and blocks by name or description. Use this when you know what you need but not the exact item name.",
+      inputSchema: zodToJsonSchema(searchRegistrySchema)
+    },
+    {
+      name: "get_theme",
+      description: "Get the full design token values for a PDFx theme preset (professional, modern, or minimal). Use this to understand colors, typography, and spacing before customizing documents.",
+      inputSchema: zodToJsonSchema(getThemeSchema)
+    },
+    {
+      name: "get_installation",
+      description: "Get step-by-step PDFx setup instructions for a specific framework and package manager. Use this when setting up PDFx in a new project.",
+      inputSchema: zodToJsonSchema(getInstallationSchema)
+    },
+    {
+      name: "get_add_command",
+      description: "Get the exact CLI command string to add specific PDFx components or blocks to a project.",
+      inputSchema: zodToJsonSchema(getAddCommandSchema)
+    },
+    {
+      name: "get_audit_checklist",
+      description: "Get a post-generation checklist to verify PDFx is set up correctly. Call this after adding components or generating PDF document code.",
+      inputSchema: zodToJsonSchema(z8.object({}))
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const args = request.params.arguments ?? {};
+  try {
+    switch (request.params.name) {
+      case "list_components":
+        return await listComponents();
+      case "get_component":
+        return await getComponent(getComponentSchema.parse(args));
+      case "list_blocks":
+        return await listBlocks();
+      case "get_block":
+        return await getBlock(getBlockSchema.parse(args));
+      case "search_registry":
+        return await searchRegistry(searchRegistrySchema.parse(args));
+      case "get_theme":
+        return await getTheme(getThemeSchema.parse(args));
+      case "get_installation":
+        return await getInstallation(getInstallationSchema.parse(args));
+      case "get_add_command":
+        return await getAddCommand(getAddCommandSchema.parse(args));
+      case "get_audit_checklist":
+        return await getAuditChecklist();
+      default:
+        return errorResponse(new Error(`Unknown tool: ${request.params.name}`));
+    }
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+
+// src/commands/mcp.ts
+var PDFX_CLI_PACKAGE = "pdfx-cli";
+var PDFX_MCP_VERSION = "latest";
+var CLIENTS = [
+  {
+    name: "claude",
+    label: "Claude Code",
+    configPath: ".mcp.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "cursor",
+    label: "Cursor",
+    configPath: ".cursor/mcp.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "vscode",
+    label: "VS Code",
+    configPath: ".vscode/mcp.json",
+    config: {
+      servers: {
+        pdfx: {
+          type: "stdio",
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "windsurf",
+    label: "Windsurf",
+    configPath: "mcp_config.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "qoder",
+    label: "Qoder",
+    configPath: ".qoder/mcp.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "opencode",
+    label: "opencode",
+    configPath: "opencode.json",
+    config: {
+      $schema: "https://opencode.ai/config.json",
+      mcp: {
+        pdfx: {
+          type: "local",
+          command: ["npx", "-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "antigravity",
+    label: "Antigravity",
+    configPath: ".antigravity/mcp.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  },
+  {
+    name: "other",
+    label: "Generic (any MCP client)",
+    configPath: "pdfx-mcp.json",
+    config: {
+      mcpServers: {
+        pdfx: {
+          command: "npx",
+          args: ["-y", `${PDFX_CLI_PACKAGE}@${PDFX_MCP_VERSION}`, "mcp"]
+        }
+      }
+    }
+  }
+];
+function mergeDeep(target, source) {
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const existing = result[key];
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && existing !== null && typeof existing === "object" && !Array.isArray(existing)) {
+      result[key] = mergeDeep(
+        existing,
+        value
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+async function readJsonConfig(filePath) {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+function isPdfxAlreadyConfigured(config) {
+  const withMcpServers = config;
+  const withServers = config;
+  const withMcp = config;
+  return withMcpServers.mcpServers?.pdfx !== void 0 || withServers.servers?.pdfx !== void 0 || withMcp.mcp?.pdfx !== void 0;
+}
+async function initMcpConfig(opts) {
+  let clientName = opts.client;
+  if (!clientName) {
+    const response = await prompts5({
+      type: "select",
+      name: "client",
+      message: "Which AI editor are you configuring?",
+      choices: CLIENTS.map((c) => ({ title: c.label, value: c.name }))
+    });
+    if (!response.client) {
+      process.exit(0);
+    }
+    clientName = response.client;
+  }
+  const client = CLIENTS.find((c) => c.name === clientName);
+  if (!client) {
+    process.stderr.write(`Unknown client: "${clientName}"
+`);
+    process.stderr.write(`Valid options: ${CLIENTS.map((c) => c.name).join(", ")}
+`);
+    process.exit(1);
+  }
+  const configPath = path11.resolve(process.cwd(), client.configPath);
+  const configDir = path11.dirname(configPath);
+  const existing = await readJsonConfig(configPath);
+  if (isPdfxAlreadyConfigured(existing)) {
+    const { overwrite } = await prompts5({
+      type: "confirm",
+      name: "overwrite",
+      message: `PDFx MCP is already configured in ${client.configPath}. Overwrite?`,
+      initial: false
+    });
+    if (!overwrite) {
+      process.stdout.write("\nSkipped \u2014 existing configuration kept.\n");
+      return;
+    }
+  }
+  if (!existsSync(configDir)) {
+    await mkdir(configDir, { recursive: true });
+  }
+  const merged = mergeDeep(existing, client.config);
+  await writeFile2(configPath, `${JSON.stringify(merged, null, 2)}
+`, "utf-8");
+  process.stdout.write(`
+\u2713 Wrote MCP configuration to ${client.configPath}
+`);
+  process.stdout.write(`
+Restart ${client.label} to activate the PDFx MCP server.
+`);
+  if (client.name === "claude") {
+    process.stdout.write("\nAlternatively, run:\n  claude mcp add pdfx -- npx -y pdfx-cli mcp\n");
+  }
+  if (client.name === "opencode") {
+    process.stdout.write("\nVerify: run `opencode mcp list` \u2014 pdfx should appear.\n");
+    process.stdout.write(
+      "Tip: move opencode.json to ~/.config/opencode/opencode.json for global access.\n"
+    );
+  }
+  if (client.name === "antigravity") {
+    process.stdout.write("\nVerify: open Antigravity \u2192 MCP panel \u2192 pdfx should appear.\n");
+  }
+  if (client.name === "other") {
+    process.stdout.write("\nThis file contains the PDFx MCP server configuration.\n");
+    process.stdout.write(
+      "Copy the pdfx entry into your editor's native MCP config file, or reference this file directly.\n"
+    );
+  }
+  process.stdout.write("\n");
+}
+var mcpCommand = new Command().name("mcp").description("Start the PDFx MCP server for AI editor integration").action(async () => {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+});
+mcpCommand.command("init").description("Add PDFx MCP server config to your AI editor").option(
+  "--client <name>",
+  `AI editor to configure. One of: ${CLIENTS.map((c) => c.name).join(", ")}`
+).action(initMcpConfig);
+
+// src/commands/skills.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { mkdir as mkdir2, writeFile as writeFile3 } from "fs/promises";
+import path12 from "path";
+import chalk8 from "chalk";
+import { Command as Command2 } from "commander";
+import prompts6 from "prompts";
+
+// src/skills-content.ts
+var PDFX_SKILLS_CONTENT = `# PDFx \u2014 AI Context Guide
+# Version: 1.0 | Updated: 2026 | License: MIT
+# Or run: npx pdfx-cli@latest skills init  (handles editor-specific paths & frontmatter)
+
+## What is PDFx?
+
+PDFx is an open-source, shadcn/ui-style PDF component library for React. It is built on
+@react-pdf/renderer and provides 24 type-safe components, 10 pre-built document blocks,
+3 themes, and a CLI. Components are copied into your project (not installed as npm imports
+that expose a public API).
+
+Key facts:
+- Package: pdfx-cli (the CLI that installs components)
+- Registry: https://pdfx.akashpise.dev/r/
+- Runtime: Works in browser AND Node.js (Next.js App Router, Express, etc.)
+- React version: 16.8+ (hooks required)
+- Peer dep: @react-pdf/renderer ^3.x
+
+---
+
+## Installation (one-time project setup)
+
+\`\`\`bash
+# 1. Initialize PDFx \u2014 creates src/lib/pdfx-theme.ts and installs @pdfx/shared
+npx pdfx-cli@latest init
+
+# 2. Add components you need
+npx pdfx-cli@latest add heading text table
+
+# 3. Add a pre-built block
+npx pdfx-cli@latest block add invoice-modern
+\`\`\`
+
+The init command adds a theme file at src/lib/pdfx-theme.ts. All components read from this file.
+
+---
+
+## How components work
+
+PDFx components are React components that render @react-pdf/renderer primitives (View, Text,
+Page, Document, etc.). They CANNOT render HTML or DOM elements \u2014 they only work inside a
+<Document> from @react-pdf/renderer.
+
+Usage pattern:
+\`\`\`tsx
+import { Document, Page } from '@react-pdf/renderer';
+import { Heading } from '@/components/pdfx/heading/pdfx-heading';
+import { Text } from '@/components/pdfx/text/pdfx-text';
+import { Table } from '@/components/pdfx/table/pdfx-table';
+
+export function MyDocument() {
+  return (
+    <Document>
+      <Page size="A4" style={{ padding: 40 }}>
+        <Heading level={1}>Invoice #001</Heading>
+        <Text>Thank you for your business.</Text>
+        <Table
+          headers={['Item', 'Qty', 'Price']}
+          rows={[['Design work', '1', '$4,800']]}
+        />
+      </Page>
+    </Document>
+  );
+}
+\`\`\`
+
+Rendering to PDF:
+\`\`\`tsx
+// Browser: live preview
+import { PDFViewer } from '@react-pdf/renderer';
+<PDFViewer><MyDocument /></PDFViewer>
+
+// Browser: download button
+import { PDFDownloadLink } from '@react-pdf/renderer';
+<PDFDownloadLink document={<MyDocument />} fileName="output.pdf">Download</PDFDownloadLink>
+
+// Server (Next.js App Router):
+import { renderToBuffer } from '@react-pdf/renderer';
+export async function GET() {
+  const buf = await renderToBuffer(<MyDocument />);
+  return new Response(buf, { headers: { 'Content-Type': 'application/pdf' } });
+}
+\`\`\`
+
+---
+
+## All 24 Components \u2014 Props Reference
+
+CRITICAL: These are the EXACT props. Do not invent additional props.
+
+### Heading
+\`\`\`tsx
+import { Heading } from '@/components/pdfx/heading/pdfx-heading';
+<Heading
+  level={1}           // 1 | 2 | 3 | 4 | 5 | 6 \u2014 default: 1
+  align="left"        // 'left' | 'center' | 'right' \u2014 default: 'left'
+  weight="bold"       // 'normal' | 'bold' \u2014 default: 'bold'
+  tracking="normal"   // 'tight' | 'normal' | 'wide' \u2014 default: 'normal'
+  color="#000"        // string \u2014 default: theme.colors.foreground
+  gutterBottom        // boolean \u2014 adds bottom margin
+>
+  My Heading
+</Heading>
+\`\`\`
+
+### Text
+\`\`\`tsx
+import { Text } from '@/components/pdfx/text/pdfx-text';
+<Text
+  size="md"           // 'xs' | 'sm' | 'md' | 'lg' | 'xl' \u2014 default: 'md'
+  weight="normal"     // 'normal' | 'medium' | 'semibold' | 'bold' \u2014 default: 'normal'
+  color="#000"        // string
+  align="left"        // 'left' | 'center' | 'right' | 'justify'
+  italic              // boolean
+  muted               // boolean \u2014 applies theme.colors.mutedForeground
+  gutterBottom        // boolean
+>
+  Paragraph text here.
+</Text>
+\`\`\`
+
+### Link
+\`\`\`tsx
+import { Link } from '@/components/pdfx/link/pdfx-link';
+<Link
+  href="https://example.com"  // string \u2014 required
+  size="md"                   // same as Text size
+  color="#0000ff"             // default: theme.colors.accent
+>
+  Click here
+</Link>
+\`\`\`
+
+### Divider
+\`\`\`tsx
+import { Divider } from '@/components/pdfx/divider/pdfx-divider';
+<Divider
+  thickness={1}       // number in pt \u2014 default: 1
+  color="#e4e4e7"     // string \u2014 default: theme.colors.border
+  spacing="md"        // 'sm' | 'md' | 'lg' \u2014 vertical margin
+  style="solid"       // 'solid' | 'dashed' | 'dotted'
+/>
+\`\`\`
+
+### PageBreak
+\`\`\`tsx
+import { PageBreak } from '@/components/pdfx/page-break/pdfx-page-break';
+<PageBreak /> // No props. Forces a new page.
+\`\`\`
+
+### Stack
+\`\`\`tsx
+import { Stack } from '@/components/pdfx/stack/pdfx-stack';
+<Stack
+  direction="column"   // 'row' | 'column' \u2014 default: 'column'
+  gap={8}             // number in pt \u2014 default: 0
+  align="flex-start"  // flexbox align-items
+  justify="flex-start"// flexbox justify-content
+  wrap                // boolean \u2014 flex-wrap
+>
+  {children}
+</Stack>
+\`\`\`
+
+### Section
+\`\`\`tsx
+import { Section } from '@/components/pdfx/section/pdfx-section';
+<Section
+  title="Section Title"   // string \u2014 optional
+  titleLevel={2}          // 1\u20136 \u2014 default: 2
+  padding={16}            // number | {top,right,bottom,left} \u2014 default: 0
+  bordered                // boolean \u2014 adds border around section
+  background="#f9f9f9"    // string \u2014 background color
+>
+  {children}
+</Section>
+\`\`\`
+
+### Table
+\`\`\`tsx
+import { Table } from '@/components/pdfx/table/pdfx-table';
+<Table
+  headers={['Column A', 'Column B', 'Column C']}   // string[] \u2014 required
+  rows={[['R1C1', 'R1C2', 'R1C3']]}               // string[][] \u2014 required
+  striped            // boolean \u2014 alternating row colors
+  bordered           // boolean \u2014 cell borders
+  compact            // boolean \u2014 smaller padding
+  headerBg="#18181b" // string \u2014 header background
+  headerColor="#fff" // string \u2014 header text color
+  columnWidths={[2, 1, 1]} // number[] \u2014 flex ratios
+  caption="Table 1" // string \u2014 caption below table
+/>
+\`\`\`
+
+### DataTable
+\`\`\`tsx
+import { DataTable } from '@/components/pdfx/data-table/pdfx-data-table';
+<DataTable
+  columns={[
+    { key: 'name', header: 'Name', width: 2 },
+    { key: 'amount', header: 'Amount', width: 1, align: 'right' },
+  ]}
+  data={[{ name: 'Item A', amount: '$100' }]}
+  striped
+  bordered
+  compact
+/>
+\`\`\`
+
+### List
+\`\`\`tsx
+import { List } from '@/components/pdfx/list/pdfx-list';
+<List
+  items={['First item', 'Second item', 'Third item']}  // string[] \u2014 required
+  ordered           // boolean \u2014 numbered list (default: bulleted)
+  bullet="\u2022"        // string \u2014 custom bullet character
+  indent={16}       // number \u2014 left indent in pt
+  spacing="sm"      // 'sm' | 'md' | 'lg' \u2014 gap between items
+/>
+\`\`\`
+
+### Card
+\`\`\`tsx
+import { Card } from '@/components/pdfx/card/pdfx-card';
+<Card
+  padding={16}       // number \u2014 default: 16
+  bordered           // boolean \u2014 default: true
+  shadow             // boolean
+  background="#fff"  // string
+  borderColor="#e4e4e7" // string
+  borderRadius={4}   // number in pt
+>
+  {children}
+</Card>
+\`\`\`
+
+### Form (read-only form fields for PDFs)
+\`\`\`tsx
+import { Form } from '@/components/pdfx/form/pdfx-form';
+<Form
+  fields={[
+    { label: 'Full Name', value: 'John Doe' },
+    { label: 'Email', value: 'john@example.com' },
+    { label: 'Notes', value: 'Some notes here', multiline: true },
+  ]}
+  columns={2}      // 1 | 2 \u2014 default: 1
+  bordered         // boolean
+/>
+\`\`\`
+
+### Signature
+\`\`\`tsx
+import { PdfSignatureBlock } from '@/components/pdfx/signature/pdfx-signature';
+<PdfSignatureBlock
+  name="Sarah Chen"           // string \u2014 printed name below line
+  title="Engineering Lead"    // string \u2014 title/role below name
+  date="2024-12-12"          // string \u2014 formatted date
+  lineWidth={120}             // number \u2014 signature line width in pt
+  showDate                    // boolean \u2014 default: true
+/>
+\`\`\`
+
+### PageHeader
+\`\`\`tsx
+import { PageHeader } from '@/components/pdfx/page-header/pdfx-page-header';
+<PageHeader
+  title="Document Title"
+  subtitle="Subtitle or tagline"
+  logo={{ src: 'https://...', width: 60, height: 30 }}
+  bordered        // boolean \u2014 adds bottom border
+/>
+\`\`\`
+
+### PageFooter
+\`\`\`tsx
+import { PageFooter } from '@/components/pdfx/page-footer/pdfx-page-footer';
+<PageFooter
+  left="\xA9 2024 Acme Corp"
+  center="Confidential"
+  right="Page 1 of 1"
+  bordered         // boolean \u2014 top border
+/>
+\`\`\`
+
+### Badge
+\`\`\`tsx
+import { Badge } from '@/components/pdfx/badge/pdfx-badge';
+// Use label prop OR children (string only \u2014 not a React node)
+<Badge
+  label="PAID"       // string \u2014 preferred API
+  variant="success"  // 'default' | 'success' | 'warning' | 'error' | 'info' | 'outline'
+  size="md"          // 'sm' | 'md' | 'lg'
+/>
+// OR
+<Badge variant="success">PAID</Badge>
+\`\`\`
+
+### KeyValue
+\`\`\`tsx
+import { KeyValue } from '@/components/pdfx/key-value/pdfx-key-value';
+<KeyValue
+  items={[
+    { label: 'Invoice #', value: 'INV-001' },
+    { label: 'Due Date', value: 'Jan 31, 2025' },
+  ]}
+  columns={2}         // 1 | 2 | 3 \u2014 default: 1
+  labelWidth={80}     // number in pt
+  colon               // boolean \u2014 adds colon after label
+/>
+\`\`\`
+
+### KeepTogether
+\`\`\`tsx
+import { KeepTogether } from '@/components/pdfx/keep-together/pdfx-keep-together';
+// Prevents page breaks inside its children
+<KeepTogether>
+  <Heading level={3}>Section that must not split</Heading>
+  <Table headers={[...]} rows={[...]} />
+</KeepTogether>
+\`\`\`
+
+### PdfImage
+\`\`\`tsx
+import { PdfImage } from '@/components/pdfx/pdf-image/pdfx-pdf-image';
+<PdfImage
+  src="https://example.com/image.png"  // string | base64 \u2014 required
+  width={200}         // number in pt
+  height={150}        // optional \u2014 maintains aspect ratio if omitted
+  alt="Description"   // string \u2014 for accessibility
+  objectFit="cover"   // 'cover' | 'contain' | 'fill'
+  borderRadius={4}    // number
+/>
+\`\`\`
+
+### Graph
+\`\`\`tsx
+import { Graph } from '@/components/pdfx/graph/pdfx-graph';
+<Graph
+  type="bar"          // 'bar' | 'line' | 'pie' | 'donut'
+  data={[
+    { label: 'Q1', value: 4200 },
+    { label: 'Q2', value: 6100 },
+  ]}
+  width={400}         // number in pt
+  height={200}        // number in pt
+  title="Revenue"     // string \u2014 optional
+  showValues          // boolean \u2014 show value labels
+  showLegend          // boolean
+  colors={['#18181b', '#71717a']}  // string[] \u2014 bar/slice colors
+/>
+\`\`\`
+
+### PageNumber
+\`\`\`tsx
+import { PageNumber } from '@/components/pdfx/page-number/pdfx-page-number';
+<PageNumber
+  format="Page {current} of {total}"  // string template
+  size="sm"
+  align="right"
+/>
+\`\`\`
+
+### Watermark
+\`\`\`tsx
+import { PdfWatermark } from '@/components/pdfx/watermark/pdfx-watermark';
+<PdfWatermark
+  text="CONFIDENTIAL"   // string \u2014 required
+  opacity={0.08}        // number 0\u20131 \u2014 default: 0.08
+  angle={-35}           // number in degrees \u2014 default: -35
+  fontSize={72}         // number \u2014 default: 72
+  color="#000000"       // string
+/>
+\`\`\`
+
+### QRCode
+\`\`\`tsx
+import { PdfQRCode } from '@/components/pdfx/qrcode/pdfx-qrcode';
+<PdfQRCode
+  value="https://example.com"  // string \u2014 required
+  size={80}                    // number in pt \u2014 default: 80
+  errorCorrectionLevel="M"    // 'L' | 'M' | 'Q' | 'H'
+/>
+\`\`\`
+
+### Alert
+\`\`\`tsx
+import { Alert } from '@/components/pdfx/alert/pdfx-alert';
+<Alert
+  variant="info"      // 'info' | 'success' | 'warning' | 'error'
+  title="Note"        // string \u2014 optional bold title
+>
+  This is an informational note.
+</Alert>
+\`\`\`
+
+---
+
+## Pre-built Blocks
+
+Blocks are complete document templates. Add them with:
+\`\`\`bash
+npx pdfx-cli@latest block add <block-name>
+\`\`\`
+
+### Invoice Blocks
+- invoice-modern \u2014 Clean two-column layout with totals table
+- invoice-minimal \u2014 Stripped-down, typography-focused
+- invoice-corporate \u2014 Header with logo area, full itemization
+- invoice-creative \u2014 Accent colors, bold layout
+
+### Report Blocks
+- report-executive \u2014 KPI cards + summary table, 2-page
+- report-annual \u2014 Multi-section with charts and appendix
+- report-financial \u2014 P&L / balance sheet focus
+- report-marketing \u2014 Campaign metrics with graphs
+- report-technical \u2014 Code-friendly, monospace sections
+
+### Contract Block
+- contract-standard \u2014 Signature page, numbered clauses, party info
+
+Blocks are added as full React components in your project. Customize all content props.
+
+---
+
+## Theming
+
+### The theme file
+
+After \`npx pdfx-cli@latest init\`, a file is created at src/lib/pdfx-theme.ts.
+Every PDFx component reads from this file \u2014 change a token once, all components update.
+
+\`\`\`typescript
+export const theme: PdfxTheme = {
+  name: 'my-brand',
+  colors: {
+    primary: '#2563eb',
+    accent: '#7c3aed',
+    foreground: '#1a1a1a',
+    background: '#ffffff',
+    muted: '#f4f4f5',
+    mutedForeground: '#71717a',
+    primaryForeground: '#ffffff',
+    border: '#e4e4e7',
+    destructive: '#dc2626',
+    success: '#16a34a',
+    warning: '#d97706',
+    info: '#0ea5e9',
+  },
+  typography: {
+    heading: { fontFamily: 'Helvetica-Bold', fontWeight: 700, lineHeight: 1.2,
+      fontSize: { h1: 36, h2: 28, h3: 22, h4: 18, h5: 15, h6: 12 } },
+    body: { fontFamily: 'Helvetica', fontSize: 11, lineHeight: 1.5 },
+  },
+  // primitives, spacing, page \u2014 all required (scaffolded by init)
+};
+\`\`\`
+
+### Theme presets
+\`\`\`bash
+npx pdfx-cli@latest theme init              # scaffold blank theme
+npx pdfx-cli@latest theme switch modern     # switch preset: professional | modern | minimal
+npx pdfx-cli@latest theme validate          # validate your theme file
+\`\`\`
+
+---
+
+## CLI Reference
+
+\`\`\`bash
+# Setup
+npx pdfx-cli@latest init                          # Initialize PDFx in project
+npx pdfx-cli@latest add <component>               # Add a component
+npx pdfx-cli@latest add <comp1> <comp2>           # Add multiple
+npx pdfx-cli@latest block add <block>             # Add a block
+
+# Theme
+npx pdfx-cli@latest theme init                    # Create theme file
+npx pdfx-cli@latest theme switch professional     # Switch preset
+npx pdfx-cli@latest theme validate                # Validate theme
+
+# MCP (AI editor integration)
+npx pdfx-cli@latest mcp                           # Start MCP server
+npx pdfx-cli@latest mcp init                      # Configure editor (interactive)
+npx pdfx-cli@latest mcp init --client claude      # Claude Code  (.mcp.json)
+npx pdfx-cli@latest mcp init --client cursor      # Cursor        (.cursor/mcp.json)
+npx pdfx-cli@latest mcp init --client vscode      # VS Code       (.vscode/mcp.json)
+npx pdfx-cli@latest mcp init --client windsurf    # Windsurf      (mcp_config.json)
+npx pdfx-cli@latest mcp init --client qoder       # Qoder         (.qoder/mcp.json)
+npx pdfx-cli@latest mcp init --client opencode    # opencode      (opencode.json)
+npx pdfx-cli@latest mcp init --client antigravity # Antigravity   (.antigravity/mcp.json)
+
+# Skills file (AI context document)
+npx pdfx-cli@latest skills init                      # Write skills file (interactive)
+npx pdfx-cli@latest skills init --platform claude    # CLAUDE.md
+npx pdfx-cli@latest skills init --platform cursor    # .cursor/rules/pdfx.mdc
+npx pdfx-cli@latest skills init --platform vscode    # .github/copilot-instructions.md
+npx pdfx-cli@latest skills init --platform windsurf  # .windsurf/rules/pdfx.md
+npx pdfx-cli@latest skills init --platform opencode  # AGENTS.md
+npx pdfx-cli@latest skills init --platform antigravity # .antigravity/context.md
+\`\`\`
+
+---
+
+## Common patterns
+
+### Full invoice from scratch
+\`\`\`tsx
+import { Document, Page } from '@react-pdf/renderer';
+import { Heading } from '@/components/pdfx/heading/pdfx-heading';
+import { KeyValue } from '@/components/pdfx/key-value/pdfx-key-value';
+import { Table } from '@/components/pdfx/table/pdfx-table';
+import { Divider } from '@/components/pdfx/divider/pdfx-divider';
+import { Badge } from '@/components/pdfx/badge/pdfx-badge';
+import { PageFooter } from '@/components/pdfx/page-footer/pdfx-page-footer';
+
+export function InvoiceDoc() {
+  return (
+    <Document>
+      <Page size="A4" style={{ padding: 48, fontFamily: 'Helvetica' }}>
+        <Heading level={1}>Invoice #INV-001</Heading>
+        <KeyValue
+          items={[
+            { label: 'Date', value: 'Jan 1, 2025' },
+            { label: 'Due', value: 'Jan 31, 2025' },
+          ]}
+          columns={2}
+        />
+        <Divider spacing="md" />
+        <Table
+          headers={['Description', 'Qty', 'Total']}
+          rows={[
+            ['Design System', '1', '$4,800'],
+            ['Development', '2', '$9,600'],
+          ]}
+          striped
+          bordered
+          columnWidths={[3, 1, 1]}
+        />
+        <Badge label="PAID" variant="success" />
+        <PageFooter left="Acme Corp" right="Page 1 of 1" bordered />
+      </Page>
+    </Document>
+  );
+}
+\`\`\`
+
+### Preventing page splits
+\`\`\`tsx
+// Wrap anything that must stay together across page boundaries
+<KeepTogether>
+  <Heading level={3}>Q3 Summary</Heading>
+  <Table headers={['Metric', 'Value']} rows={data} />
+</KeepTogether>
+\`\`\`
+
+### Server-side generation (Next.js)
+\`\`\`typescript
+// app/api/invoice/route.ts
+import { renderToBuffer } from '@react-pdf/renderer';
+import { InvoiceDoc } from '@/components/pdf/invoice';
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const id = searchParams.get('id');
+  const data = await fetchInvoice(id);
+  const buf = await renderToBuffer(<InvoiceDoc data={data} />);
+  return new Response(buf, {
+    headers: {
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': \`inline; filename="invoice-\${id}.pdf"\`,
+    },
+  });
+}
+\`\`\`
+
+---
+
+## react-pdf layout constraints (CRITICAL)
+
+@react-pdf/renderer enforces strict separation between layout containers and text:
+
+- **View** is a layout container (like a div). It can contain other Views and Text nodes.
+- **Text** is a text container. It can contain strings or nested Text nodes.
+- **NEVER mix View and inline text in a flex row.** This causes irrecoverable layout failures.
+
+\`\`\`tsx
+// \u2717 WRONG \u2014 mixing View and text siblings in a flex row
+<View style={{ flexDirection: 'row' }}>
+  <View style={{ width: 100 }}>...</View>
+  Some text here   {/* \u2190 this text sibling crashes the layout */}
+</View>
+
+// \u2713 CORRECT \u2014 wrap all text siblings in <Text>
+<View style={{ flexDirection: 'row' }}>
+  <View style={{ width: 100 }}>...</View>
+  <Text>Some text here</Text>
+</View>
+\`\`\`
+
+---
+
+## Anti-patterns to avoid
+
+- DO NOT use HTML elements inside PDFx components (no <div>, <p>, <span>)
+- DO NOT import from @react-pdf/renderer inside PDFx component files \u2014 they already wrap it
+- DO NOT use CSS classes or Tailwind inside PDF components \u2014 use style props or theme tokens
+- DO NOT use window, document, or browser APIs in server-rendered PDF routes
+- DO NOT install components with npm \u2014 always use the CLI: npx pdfx-cli@latest add <name>
+- DO NOT place raw text siblings next to View elements in a flex row (react-pdf constraint)
+- DO NOT pass React nodes (JSX) as Badge children \u2014 only plain strings are supported
+
+---
+
+## MCP Server (for AI editors)
+
+The PDFx MCP server gives AI editors live access to the entire registry:
+\`\`\`bash
+npx pdfx-cli@latest mcp init   # interactive setup for your editor
+\`\`\`
+Supported: Claude Code, Cursor, VS Code, Windsurf, Qoder, opencode, Antigravity
+
+Tools: list_components, get_component, list_blocks, get_block, search_registry,
+       get_theme, get_installation, get_add_command, get_audit_checklist
+
+---
+# End of PDFx AI Context Guide
+`;
+
+// src/commands/skills.ts
+var PLATFORMS = [
+  {
+    name: "claude",
+    label: "Claude Code",
+    file: "CLAUDE.md",
+    hint: "Project-level CLAUDE.md \u2014 read automatically by Claude Code",
+    verifyStep: "Claude Code picks up CLAUDE.md automatically on next session."
+  },
+  {
+    // .cursor/rules/*.mdc with alwaysApply: true — Cursor's current rules format (not .cursorrules).
+    name: "cursor",
+    label: "Cursor",
+    file: ".cursor/rules/pdfx.mdc",
+    hint: ".cursor/rules/pdfx.mdc \u2014 Cursor rules file with alwaysApply frontmatter",
+    verifyStep: "Cursor reads .cursor/rules/*.mdc automatically. Restart Cursor to be sure.",
+    frontmatter: "---\ndescription: PDFx PDF component library AI context\nglobs: \nalwaysApply: true\n---\n\n"
+  },
+  {
+    name: "vscode",
+    label: "VS Code (Copilot)",
+    file: ".github/copilot-instructions.md",
+    hint: ".github/copilot-instructions.md \u2014 read by GitHub Copilot Chat",
+    verifyStep: "GitHub Copilot reads copilot-instructions.md from .github/. Commit the file so teammates get it too."
+  },
+  {
+    name: "windsurf",
+    label: "Windsurf",
+    file: ".windsurfrules",
+    hint: ".windsurfrules \u2014 applied to all Cascade AI interactions",
+    verifyStep: "Windsurf applies .windsurfrules automatically."
+  },
+  {
+    name: "qoder",
+    label: "Qoder",
+    file: ".qoder/rules.md",
+    hint: ".qoder/rules.md \u2014 Qoder project-level AI context",
+    verifyStep: "Restart Qoder and check that the AI context is loaded from .qoder/rules.md."
+  },
+  {
+    name: "opencode",
+    label: "opencode",
+    file: "AGENTS.md",
+    hint: "AGENTS.md \u2014 opencode project context file",
+    verifyStep: "opencode reads AGENTS.md from the project root. Start a new session to verify."
+  },
+  {
+    name: "antigravity",
+    label: "Antigravity",
+    file: ".antigravity/context.md",
+    hint: ".antigravity/context.md \u2014 Antigravity project context",
+    verifyStep: "Verify the context path against your Antigravity version. Restart to activate."
+  },
+  {
+    name: "other",
+    label: "Generic (any AI tool)",
+    file: "pdfx-context.md",
+    hint: "pdfx-context.md \u2014 reference this from your editor's rules file",
+    verifyStep: "Reference pdfx-context.md from your editor's rules file (e.g. .cursorrules, CLAUDE.md)."
+  }
+];
+var PDFX_MARKER = "# PDFx \u2014 AI Context Guide";
+function fileHasPdfxContent(filePath) {
+  try {
+    return readFileSync(filePath, "utf-8").includes(PDFX_MARKER);
+  } catch {
+    return false;
+  }
+}
+async function skillsInit(opts) {
+  let platformName = opts.platform;
+  if (!platformName) {
+    const response = await prompts6({
+      type: "select",
+      name: "platform",
+      message: "Which AI editor are you targeting?",
+      choices: PLATFORMS.map((p) => ({
+        title: p.label,
+        value: p.name,
+        description: p.hint
+      }))
+    });
+    if (!response.platform) {
+      process.exit(0);
+    }
+    platformName = response.platform;
+  }
+  const platform = PLATFORMS.find((p) => p.name === platformName);
+  if (!platform) {
+    process.stderr.write(chalk8.red(`\u2716 Unknown platform: "${platformName}"
+`));
+    process.stderr.write(
+      chalk8.dim(`  Valid options: ${PLATFORMS.map((p) => p.name).join(", ")}
+`)
+    );
+    process.exit(1);
+  }
+  const filePath = path12.resolve(process.cwd(), platform.file);
+  const fileDir = path12.dirname(filePath);
+  const relativeFile = platform.file;
+  const alreadyExists = existsSync2(filePath);
+  const hasPdfxContent = alreadyExists && fileHasPdfxContent(filePath);
+  let shouldAppend = opts.append ?? false;
+  if (alreadyExists) {
+    if (shouldAppend || opts.yes) {
+    } else if (hasPdfxContent) {
+      const { action: action2 } = await prompts6({
+        type: "select",
+        name: "action",
+        message: `${relativeFile} already contains PDFx context. What would you like to do?`,
+        choices: [
+          { title: "Overwrite (replace PDFx section with latest content)", value: "overwrite" },
+          { title: "Skip", value: "skip" }
+        ]
+      });
+      if (!action2 || action2 === "skip") {
+        process.stdout.write(chalk8.dim("\nSkipped \u2014 existing file kept.\n\n"));
+        return;
+      }
+    } else {
+      const { action: action2 } = await prompts6({
+        type: "select",
+        name: "action",
+        message: `${relativeFile} already exists. What would you like to do?`,
+        choices: [
+          {
+            title: "Append (add PDFx context at the end, keep existing content)",
+            value: "append"
+          },
+          { title: "Overwrite (replace entire file with PDFx context)", value: "overwrite" },
+          { title: "Skip", value: "skip" }
+        ]
+      });
+      if (!action2 || action2 === "skip") {
+        process.stdout.write(chalk8.dim("\nSkipped \u2014 existing file kept.\n\n"));
+        return;
+      }
+      if (action2 === "append") {
+        shouldAppend = true;
+      }
+    }
+  }
+  if (!existsSync2(fileDir)) {
+    await mkdir2(fileDir, { recursive: true });
+  }
+  const appendContent = `
+
+---
+
+${PDFX_SKILLS_CONTENT}`;
+  const content = shouldAppend ? appendContent : PDFX_SKILLS_CONTENT;
+  if (shouldAppend && alreadyExists) {
+    const existing = readFileSync(filePath, "utf-8");
+    await writeFile3(filePath, `${existing.trimEnd()}${content}
+`, "utf-8");
+  } else {
+    await writeFile3(filePath, `${content}
+`, "utf-8");
+  }
+  const action = shouldAppend && alreadyExists ? "Appended PDFx context to" : "Wrote";
+  process.stdout.write(`
+${chalk8.green("\u2713")} ${action} ${chalk8.cyan(relativeFile)}
+`);
+  process.stdout.write(`
+${chalk8.dim(platform.verifyStep)}
+
+`);
+  if (platform.name === "claude") {
+    process.stdout.write(
+      chalk8.dim(
+        "Tip: if you also use the MCP server, CLAUDE.md + MCP gives the AI\nthe best possible PDFx knowledge \u2014 static props reference + live registry.\n\n"
+      )
+    );
+  }
+}
+var skillsCommand = new Command2().name("skills").description("Manage the PDFx AI context (skills) file for your editor");
+skillsCommand.command("init").description("Write the PDFx skills file to your AI editor's context file").option(
+  "-p, --platform <name>",
+  `Target AI editor. One of: ${PLATFORMS.map((p) => p.name).join(", ")}`
+).option("-y, --yes", "Overwrite existing file without prompting").option("-a, --append", "Append PDFx context to an existing file instead of overwriting").action(skillsInit);
+skillsCommand.command("list").description("List all supported AI editor platforms").action(() => {
+  process.stdout.write("\n");
+  process.stdout.write(chalk8.bold("  Supported platforms\n\n"));
+  for (const p of PLATFORMS) {
+    process.stdout.write(`  ${chalk8.cyan(p.name.padEnd(12))} ${chalk8.dim("\u2192")} ${p.file}
+`);
+  }
+  process.stdout.write("\n");
+  process.stdout.write(
+    chalk8.dim("  Usage: npx pdfx-cli@latest skills init --platform <name>\n\n")
+  );
+});
+
+// src/commands/theme.ts
+import fs8 from "fs";
+import path13 from "path";
+import chalk9 from "chalk";
+import ora7 from "ora";
+import prompts7 from "prompts";
+import ts from "typescript";
+async function themeInit() {
+  const configPath = path13.join(process.cwd(), "pdfx.json");
+  if (!checkFileExists(configPath)) {
+    console.error(chalk9.red("\nError: pdfx.json not found"));
+    console.log(chalk9.yellow("\n  PDFx is not initialized in this project.\n"));
+    console.log(chalk9.cyan("  Run: pdfx init"));
+    console.log(chalk9.dim("  This will set up your project configuration and theme.\n"));
+    process.exit(1);
+  }
+  console.log(chalk9.bold.cyan("\n  PDFx Theme Setup\n"));
+  const answers = await prompts7(
+    [
+      {
+        type: "select",
+        name: "preset",
+        message: "Choose a theme preset:",
+        choices: [
+          {
+            title: "Professional",
+            description: "Serif headings, navy colors, generous margins",
+            value: "professional"
+          },
+          {
+            title: "Modern",
+            description: "Sans-serif, vibrant purple, tight spacing",
+            value: "modern"
+          },
+          {
+            title: "Minimal",
+            description: "Monospace headings, stark black, maximum whitespace",
+            value: "minimal"
+          }
+        ],
+        initial: 0
+      },
+      {
+        type: "text",
+        name: "themePath",
+        message: "Where should we create the theme file?",
+        initial: DEFAULTS.THEME_FILE,
+        format: normalizeThemePath,
+        validate: validateThemePath
+      }
+    ],
+    {
+      onCancel: () => {
+        console.log(chalk9.yellow("\nTheme setup cancelled."));
+        process.exit(0);
+      }
+    }
+  );
+  if (!answers.preset || !answers.themePath) {
+    console.error(chalk9.red("Missing required fields."));
+    process.exit(1);
+  }
+  const presetName = answers.preset;
+  const themePath = answers.themePath;
+  const preset = themePresets[presetName];
+  const spinner = ora7(`Scaffolding ${presetName} theme...`).start();
+  try {
+    const absThemePath = path13.resolve(process.cwd(), themePath);
+    writeFile(absThemePath, generateThemeFile(preset));
+    const contextPath = path13.join(path13.dirname(absThemePath), "pdfx-theme-context.tsx");
+    writeFile(contextPath, generateThemeContextFile());
+    spinner.succeed(`Created ${themePath} with ${presetName} theme`);
+    if (checkFileExists(configPath)) {
+      try {
+        const rawConfig = readJsonFile(configPath);
+        const result = configSchema.safeParse(rawConfig);
+        if (result.success) {
+          const updatedConfig = { ...result.data, theme: themePath };
+          writeFile(configPath, JSON.stringify(updatedConfig, null, 2));
+          console.log(chalk9.green("  Updated pdfx.json with theme path"));
+        }
+      } catch {
+        console.log(chalk9.yellow('  Could not update pdfx.json \u2014 add "theme" field manually'));
+      }
+    }
+    console.log(chalk9.dim(`
+  Edit ${themePath} to customize your theme.
+`));
+  } catch (error) {
+    spinner.fail("Failed to create theme file");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk9.dim(`  ${message}`));
+    process.exit(1);
+  }
+}
+async function themeSwitch(presetName) {
+  const resolvedPreset = presetName === "default" ? "professional" : presetName;
+  const validPresets = Object.keys(themePresets);
+  if (!validPresets.includes(resolvedPreset)) {
+    console.error(chalk9.red(`\u2716 Invalid theme preset: "${presetName}"`));
+    console.log(chalk9.dim(`  Available presets: ${validPresets.join(", ")}, default
+`));
+    console.log(chalk9.dim("  Usage: pdfx theme switch <preset>"));
+    process.exit(1);
+  }
+  const validatedPreset = resolvedPreset;
+  const configPath = path13.join(process.cwd(), "pdfx.json");
+  if (!checkFileExists(configPath)) {
+    console.error(chalk9.red('No pdfx.json found. Run "npx pdfx-cli@latest init" first.'));
+    process.exit(1);
+  }
+  const rawConfig = readJsonFile(configPath);
+  const result = configSchema.safeParse(rawConfig);
+  if (!result.success) {
+    console.error(chalk9.red("Invalid pdfx.json configuration."));
+    process.exit(1);
+  }
+  const config = result.data;
+  if (!config.theme) {
+    console.error(
+      chalk9.red(
+        'No theme path in pdfx.json. Run "npx pdfx-cli@latest theme init" to set up theming.'
+      )
+    );
+    process.exit(1);
+  }
+  const answer = await prompts7({
+    type: "confirm",
+    name: "confirm",
+    message: `This will overwrite ${config.theme} with the ${validatedPreset} preset. Continue?`,
+    initial: false
+  });
+  if (!answer.confirm) {
+    console.log(chalk9.yellow("Cancelled."));
+    return;
+  }
+  const spinner = ora7(`Switching to ${validatedPreset} theme...`).start();
+  try {
+    const preset = themePresets[validatedPreset];
+    const absThemePath = path13.resolve(process.cwd(), config.theme);
+    writeFile(absThemePath, generateThemeFile(preset));
+    const contextPath = path13.join(path13.dirname(absThemePath), "pdfx-theme-context.tsx");
+    if (!checkFileExists(contextPath)) {
+      writeFile(contextPath, generateThemeContextFile());
+    }
+    spinner.succeed(`Switched to ${validatedPreset} theme`);
+  } catch (error) {
+    spinner.fail("Failed to switch theme");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk9.dim(`  ${message}`));
+    process.exit(1);
+  }
+}
+function toPlainValue(node) {
+  if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isParenthesizedExpression(node)) {
+    return toPlainValue(node.expression);
+  }
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isNumericLiteral(node)) {
+    return Number(node.text);
+  }
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+    const n = toPlainValue(node.operand);
+    return typeof n === "number" ? -n : void 0;
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements.map(
+      (el) => ts.isSpreadElement(el) ? void 0 : toPlainValue(el)
+    );
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    const out = {};
+    for (const prop of node.properties) {
+      if (!ts.isPropertyAssignment(prop)) return void 0;
+      if (ts.isComputedPropertyName(prop.name)) return void 0;
+      const key = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) || ts.isNumericLiteral(prop.name) ? prop.name.text : void 0;
+      if (!key) return void 0;
+      const value = toPlainValue(prop.initializer);
+      if (value === void 0) return void 0;
+      out[key] = value;
+    }
+    return out;
+  }
+  return void 0;
+}
+function parseThemeObject(themePath) {
+  const content = fs8.readFileSync(themePath, "utf-8");
+  const sourceFile = ts.createSourceFile(
+    themePath,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    const isExported = stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name) || decl.name.text !== "theme" || !decl.initializer) continue;
+      const parsed = toPlainValue(decl.initializer);
+      if (parsed === void 0) {
+        throw new Error(
+          "Could not statically parse exported theme object. Keep `export const theme = { ... }` as a plain object literal."
+        );
+      }
+      return parsed;
+    }
+  }
+  throw new Error("No exported `theme` object found.");
+}
+async function themeValidate() {
+  const configPath = path13.join(process.cwd(), "pdfx.json");
+  if (!checkFileExists(configPath)) {
+    console.error(chalk9.red('No pdfx.json found. Run "npx pdfx-cli@latest init" first.'));
+    process.exit(1);
+  }
+  const rawConfig = readJsonFile(configPath);
+  const configResult = configSchema.safeParse(rawConfig);
+  if (!configResult.success) {
+    console.error(chalk9.red("Invalid pdfx.json configuration."));
+    process.exit(1);
+  }
+  if (!configResult.data.theme) {
+    console.error(
+      chalk9.red(
+        'No theme path in pdfx.json. Run "npx pdfx-cli@latest theme init" to set up theming.'
+      )
+    );
+    process.exit(1);
+  }
+  const absThemePath = path13.resolve(process.cwd(), configResult.data.theme);
+  if (!checkFileExists(absThemePath)) {
+    console.error(chalk9.red(`Theme file not found: ${configResult.data.theme}`));
+    process.exit(1);
+  }
+  const spinner = ora7("Validating theme file...").start();
+  try {
+    const parsedTheme = parseThemeObject(absThemePath);
+    const result = themeSchema.safeParse(parsedTheme);
+    if (!result.success) {
+      const issues = result.error.issues.map((issue) => `  \u2192 ${chalk9.yellow(issue.path.join("."))}: ${issue.message}`).join("\n");
+      spinner.fail("Theme validation failed");
+      console.log(chalk9.red("\n  Missing or invalid fields:\n"));
+      console.log(issues);
+      console.log(chalk9.dim("\n  Fix these fields in your theme file and run validate again.\n"));
+      process.exit(1);
+    }
+    spinner.succeed("Theme file is valid");
+    console.log(chalk9.dim(`
+  Validated: ${configResult.data.theme}
+`));
+  } catch (error) {
+    spinner.fail("Failed to validate theme");
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk9.dim(`  ${message}`));
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+function getVersion() {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../package.json");
+    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var program = new Command3();
+program.name("pdfx").description("CLI for PDFx components").version(getVersion());
+program.configureOutput({
+  writeErr: (str) => {
+    const message = str.replace(/^error:\s*/i, "").trimEnd();
+    process.stderr.write(chalk10.red(`\u2716 ${message}
+`));
+  }
+});
+program.command("init").description("Initialize pdfx in your project").option("-y, --yes", "Accept all defaults without prompting (non-interactive / CI mode)").action((options) => init(options));
+program.command("add <components...>").description("Add components to your project").option("-f, --force", "Overwrite existing files without prompting").option("-r, --registry <url>", "Override registry URL").option("--install-deps", "Install missing component dependencies without prompting").option("--strict-deps", "Fail when any runtime or dev dependency is missing").action(
+  (components, options) => add(components, options)
+);
+program.command("list").description("List available components from registry").action(list);
+program.command("diff <components...>").description("Compare local components with registry versions").action(diff);
+var themeCmd = program.command("theme").description("Manage PDF themes");
+themeCmd.command("init").description("Initialize or replace the theme file").action(themeInit);
+themeCmd.command("switch <preset>").description("Switch to a preset theme (professional, modern, minimal)").action(themeSwitch);
+themeCmd.command("validate").description("Validate your theme file").action(themeValidate);
+program.addCommand(mcpCommand);
+program.addCommand(skillsCommand);
+var blockCmd = program.command("block").description("Manage PDF blocks (copy-paste designs)");
+blockCmd.command("add <blocks...>").description("Add blocks to your project").option("-f, --force", "Overwrite existing files without prompting").action((blocks, options) => blockAdd(blocks, options));
+blockCmd.command("list").description("List available blocks from registry").action(blockList);
+try {
+  await program.parseAsync();
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(chalk10.red(`\u2716 ${message}
+`));
+  process.exitCode = 1;
+}