pdfx-cli 0.4.1 → 0.4.3

package/dist/index.js

@@ -2386,8 +2386,21 @@ async function getAuditChecklist() {
     \`\`\`
 
     ### "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.
+    \`@react-pdf/renderer\` renders synchronously. Hooks that depend on browser APIs or
+    async side effects do not work in the PDF render path.
+
+    **Do NOT use inside a PDFx component:**
+    - \`useEffect\` / \`useLayoutEffect\` — no browser lifecycle in PDF rendering
+    - \`useRef\` for DOM nodes — no DOM exists in the PDF render tree
+    - Any hook that calls browser globals (\`window\`, \`document\`, \`navigator\`)
+
+    **These ARE valid inside PDFx components:**
+    - PDFx framework hooks: \`usePdfxTheme()\`, \`useSafeMemo()\`
+    - Custom hooks that are pure functions with no browser-API dependencies
+    - Data passed down as props from a parent client component
+
+    If you see this error in a wrapper component you wrote, move the browser hook
+    to the nearest client component and pass the result down as a prop.
 
     ### "Text strings must be rendered inside \`<Text>\` component"
     Wrap all string literals in \`<Text>\` from \`@react-pdf/renderer\`:
@@ -2587,7 +2600,7 @@ async function getComponent(args) {
   const primaryContent = item.files[0]?.content ?? "";
   const primaryPath = item.files[0]?.path ?? "";
   const exportNames = extractAllExportNames(primaryContent);
-  const mainExport = extractExportName(primaryContent);
+  const mainExport = extractExportName(primaryContent, args.component);
   const exportSection = exportNames.length > 0 ? dedent4`
           ## Exports
           **Main component export:** \`${mainExport ?? exportNames[0]}\`
@@ -2632,11 +2645,18 @@ async function getComponent(args) {
     ${fileSources}
   `);
 }
-function extractExportName(source) {
+function extractExportName(source, componentName) {
   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;
+  const matches = [...source.matchAll(/export\s+function\s+([A-Z][A-Za-z0-9]*)/g)];
+  const names = matches.map((m) => m[1]).filter(Boolean);
+  if (names.length === 0) return null;
+  if (!componentName) return names[0];
+  const norm = componentName.replace(/-/g, "").toLowerCase();
+  const exact = names.find((n) => n.toLowerCase() === norm);
+  if (exact) return exact;
+  const suffix = names.find((n) => n.toLowerCase().endsWith(norm));
+  if (suffix) return suffix;
+  return names[0];
 }
 function extractAllExportNames(source) {
   const seen = /* @__PURE__ */ new Set();
@@ -2845,7 +2865,7 @@ async function getInstallation(args) {
     | 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 |
+    | "Invalid hook call" | Browser-only hooks (\`useEffect\`, \`useRef\` for DOM) don't work in the PDF render path — move them to a parent client component and pass the result as a prop. PDFx framework hooks (\`usePdfxTheme\`, \`useSafeMemo\`) are valid inside PDF components. |
 
     ---
     Next: call \`get_audit_checklist\` to verify your setup is correct.
@@ -2969,14 +2989,13 @@ async function getTheme(args) {
 
     ## Usage in Components
     \`\`\`tsx
-    // Access theme values in a PDFx component
-    import type { PdfxTheme } from '@pdfx/shared';
+    // Access theme values in a PDFx component via the usePdfxTheme hook.
+    // @pdfx/shared is workspace-only — do NOT import from it in your components.
+    import { View, Text } from '@react-pdf/renderer';
+    import { usePdfxTheme } from '../lib/pdfx-theme-context';
 
-    interface Props {
-      theme: PdfxTheme;
-    }
-
-    export function MyComponent({ theme }: Props) {
+    export function MyComponent() {
+      const theme = usePdfxTheme();
       return (
         <View style={{ backgroundColor: theme.colors.background }}>
           <Text style={{ color: theme.colors.foreground, fontSize: theme.typography.body.fontSize }}>
@@ -3262,8 +3281,35 @@ async function initMcpConfig(opts) {
     await mkdir(configDir, { recursive: true });
   }
   const merged = mergeDeep(existing, client.config);
-  await writeFile2(configPath, `${JSON.stringify(merged, null, 2)}
-`, "utf-8");
+  const configJson = `${JSON.stringify(merged, null, 2)}
+`;
+  try {
+    const parsed = JSON.parse(configJson);
+    if (!isPdfxAlreadyConfigured(parsed)) {
+      console.error(
+        chalk8.red(
+          "\n  Config merge failed \u2014 pdfx entry not found in merged output. Please report this bug.\n"
+        )
+      );
+      process.exit(1);
+    }
+  } catch {
+    console.error(chalk8.red("\n  Config merge produced invalid JSON. Please report this bug.\n"));
+    process.exit(1);
+  }
+  await writeFile2(configPath, configJson, "utf-8");
+  try {
+    const written = await readFile(configPath, "utf-8");
+    JSON.parse(written);
+  } catch {
+    console.error(
+      chalk8.red(
+        `
+  Warning: ${client.configPath} was written but could not be read back as valid JSON.
+`
+      )
+    );
+  }
   process.stdout.write(`
 \u2713 Wrote MCP configuration to ${client.configPath}
 `);
@@ -3309,7 +3355,7 @@ import prompts6 from "prompts";
 
 // src/skills-content.ts
 var PDFX_SKILLS_CONTENT = `# PDFx \u2014 AI Context Guide
-# Version: 1.0 | Updated: 2026 | License: MIT
+# Version: 1.1 | Updated: 2026 | License: MIT
 # Or run: npx pdfx-cli@latest skills init  (handles editor-specific paths & frontmatter)
 
 ## What is PDFx?
@@ -3364,10 +3410,14 @@ export function MyDocument() {
       <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']]}
-        />
+        <Table variant="grid" zebraStripe>
+          <TableHeader>
+            <TableRow><TableCell header>Item</TableCell><TableCell header>Price</TableCell></TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow><TableCell>Design</TableCell><TableCell>$4,800</TableCell></TableRow>
+          </TableBody>
+        </Table>
       </Page>
     </Document>
   );
@@ -3403,11 +3453,14 @@ CRITICAL: These are the EXACT props. Do not invent additional props.
 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
+  align="left"        // 'left' | 'center' | 'right'
+  weight="bold"       // 'normal' | 'medium' | 'semibold' | 'bold' \u2014 default: 'bold'
+  tracking="normal"   // 'tighter' | 'tight' | 'normal' | 'wide' | 'wider' \u2014 default: 'normal'
+  color="#000"        // string \u2014 default: theme foreground. Supports theme color keys.
+  transform="uppercase" // 'uppercase' | 'lowercase' | 'capitalize'
+  noMargin            // boolean \u2014 removes top/bottom margin
+  keepWithNext        // boolean \u2014 default: true, prevents orphaned heading
+  style={...}         // Style override
 >
   My Heading
 </Heading>
@@ -3417,13 +3470,15 @@ import { Heading } from '@/components/pdfx/heading/pdfx-heading';
 \`\`\`tsx
 import { Text } from '@/components/pdfx/text/pdfx-text';
 <Text
-  size="md"           // 'xs' | 'sm' | 'md' | 'lg' | 'xl' \u2014 default: 'md'
+  variant="base"      // 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' \u2014 default: 'base'
   weight="normal"     // 'normal' | 'medium' | 'semibold' | 'bold' \u2014 default: 'normal'
-  color="#000"        // string
+  color="#000"        // string \u2014 supports theme color keys
   align="left"        // 'left' | 'center' | 'right' | 'justify'
   italic              // boolean
-  muted               // boolean \u2014 applies theme.colors.mutedForeground
-  gutterBottom        // boolean
+  decoration="none"   // 'underline' | 'line-through' | 'none'
+  transform="uppercase" // 'uppercase' | 'lowercase' | 'capitalize'
+  noMargin            // boolean \u2014 removes bottom margin
+  style={...}         // Style override
 >
   Paragraph text here.
 </Text>
@@ -3434,8 +3489,11 @@ import { Text } from '@/components/pdfx/text/pdfx-text';
 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
+  variant="default"           // 'default' | 'muted' | 'primary' \u2014 default: 'default'
+  underline="always"          // 'always' | 'none' \u2014 default: 'always'
+  align="left"                // 'left' | 'center' | 'right'
+  color="#0000ff"             // string \u2014 overrides variant color
+  style={...}                 // Style override
 >
   Click here
 </Link>
@@ -3445,10 +3503,12 @@ import { Link } from '@/components/pdfx/link/pdfx-link';
 \`\`\`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'
+  spacing="md"        // 'none' | 'sm' | 'md' | 'lg' \u2014 default: 'md'
+  variant="solid"     // 'solid' | 'dashed' | 'dotted' \u2014 default: 'solid'
+  thickness="thin"    // 'thin' | 'medium' | 'thick' \u2014 default: 'thin'
+  color="#e4e4e7"     // string \u2014 default: theme border color
+  label="or"          // string \u2014 text centered in divider line
+  width="80%"         // string | number \u2014 constrain width
 />
 \`\`\`
 
@@ -3462,11 +3522,12 @@ import { PageBreak } from '@/components/pdfx/page-break/pdfx-page-break';
 \`\`\`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
+  direction="vertical"  // 'vertical' | 'horizontal' \u2014 default: 'vertical'
+  gap="md"              // 'none' | 'sm' | 'md' | 'lg' | 'xl' \u2014 default: 'md'
+  align="start"         // 'start' | 'center' | 'end' | 'stretch'
+  justify="start"       // 'start' | 'center' | 'end' | 'between' | 'around'
+  wrap                  // boolean \u2014 flex-wrap
+  noWrap                // boolean \u2014 prevent page split
 >
   {children}
 </Stack>
@@ -3476,33 +3537,43 @@ import { Stack } from '@/components/pdfx/stack/pdfx-stack';
 \`\`\`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
+  spacing="md"         // 'none' | 'sm' | 'md' | 'lg' | 'xl' \u2014 default: 'md'
+  padding="md"         // 'none' | 'sm' | 'md' | 'lg' \u2014 optional
+  variant="default"    // 'default' | 'callout' | 'highlight' | 'card'
+  border               // boolean \u2014 adds border (default variant only)
+  background="#f9f9f9" // string \u2014 background color
+  accentColor="#2563eb" // string \u2014 left border color for callout/highlight
+  noWrap               // boolean \u2014 prevent page split
+  style={...}          // Style override
 >
   {children}
 </Section>
 \`\`\`
 
-### Table
+### Table (composable API)
 \`\`\`tsx
-import { Table } from '@/components/pdfx/table/pdfx-table';
+import { Table, TableHeader, TableBody, TableFooter, TableRow, TableCell } 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
-/>
+  variant="line"       // 'line' | 'grid' | 'minimal' | 'striped' | 'compact' | 'bordered' | 'primary-header'
+  zebraStripe          // boolean \u2014 alternating row background
+  noWrap               // boolean \u2014 prevent page split
+>
+  <TableHeader>
+    <TableRow>
+      <TableCell header>Column A</TableCell>
+      <TableCell header>Column B</TableCell>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>R1C1</TableCell>
+      <TableCell align="right" width={80}>R1C2</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
 \`\`\`
 
-### DataTable
+### DataTable (declarative API)
 \`\`\`tsx
 import { DataTable } from '@/components/pdfx/data-table/pdfx-data-table';
 <DataTable
@@ -3511,62 +3582,90 @@ import { DataTable } from '@/components/pdfx/data-table/pdfx-data-table';
     { key: 'amount', header: 'Amount', width: 1, align: 'right' },
   ]}
   data={[{ name: 'Item A', amount: '$100' }]}
-  striped
-  bordered
-  compact
+  variant="grid"       // 'line' | 'grid' | 'minimal' | 'striped' | 'compact' | 'bordered' | 'primary-header'
+  stripe               // boolean \u2014 alternating row background
+  size="default"       // 'default' | 'compact'
+  footer={{ amount: '$100' }}  // partial record for footer row
+  noWrap               // boolean \u2014 prevent page split
 />
 \`\`\`
+DataTable render prop: \`render\` and \`renderFooter\` must return @react-pdf/renderer elements
+(Text, View, Image) \u2014 NOT HTML elements. TypeScript accepts ReactNode but DOM elements crash.
 
-### List
+### PdfList
 \`\`\`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
+import { PdfList } from '@/components/pdfx/list/pdfx-list';
+<PdfList
+  items={[
+    { text: 'First item' },
+    { text: 'Second item', description: 'Details here' },
+    { text: 'Checked item', checked: true },
+    { text: 'Parent', children: [{ text: 'Nested' }] },
+  ]}
+  variant="bullet"     // 'bullet' | 'numbered' | 'checklist' | 'icon' | 'multi-level' | 'descriptive'
+  gap="sm"             // 'xs' | 'sm' | 'md' \u2014 default: 'sm'
+  noWrap               // boolean \u2014 prevent page split
 />
 \`\`\`
 
-### Card
+### PdfCard
 \`\`\`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
+import { PdfCard } from '@/components/pdfx/card/pdfx-card';
+<PdfCard
+  title="Card Title"   // string \u2014 rendered with border-bottom
+  variant="default"    // 'default' | 'bordered' | 'muted'
+  padding="md"         // 'sm' | 'md' | 'lg' \u2014 default: 'md'
+  wrap={false}         // boolean \u2014 default: false (prevents page split)
+  style={...}          // Style override
 >
   {children}
-</Card>
+</PdfCard>
 \`\`\`
 
-### Form (read-only form fields for PDFs)
+### PdfForm (read-only fillable form 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 },
+import { PdfForm } from '@/components/pdfx/form/pdfx-form';
+<PdfForm
+  title="Application Form"
+  subtitle="Please fill in all fields"
+  groups={[
+    {
+      title: 'Personal Information',
+      layout: 'two-column',     // 'single' | 'two-column' | 'three-column'
+      fields: [
+        { label: 'Full Name', hint: 'As on ID', height: 24 },
+        { label: 'Email' },
+      ],
+    },
+    {
+      title: 'Notes',
+      fields: [{ label: 'Additional Info', height: 60 }],
+    },
   ]}
-  columns={2}      // 1 | 2 \u2014 default: 1
-  bordered         // boolean
+  variant="underline"           // 'underline' | 'box' | 'outlined' | 'ghost'
+  labelPosition="above"         // 'above' | 'left' \u2014 default: 'above'
+  noWrap                        // boolean
 />
 \`\`\`
 
-### Signature
+### PdfSignatureBlock
 \`\`\`tsx
 import { PdfSignatureBlock } from '@/components/pdfx/signature/pdfx-signature';
+// Single signature
+<PdfSignatureBlock
+  variant="single"       // 'single' | 'double' | 'inline' \u2014 default: 'single'
+  label="Signature"      // string \u2014 label above line
+  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
+/>
+// Double 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
+  variant="double"
+  signers={[
+    { label: 'Authorized by', name: 'John', title: 'CEO', date: '2024-12-12' },
+    { label: 'Approved by', name: 'Jane', title: 'CFO', date: '2024-12-12' },
+  ]}
 />
 \`\`\`
 
@@ -3574,10 +3673,18 @@ import { PdfSignatureBlock } from '@/components/pdfx/signature/pdfx-signature';
 \`\`\`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
+  title="Document Title"         // string \u2014 required
+  subtitle="Subtitle"            // string
+  rightText="INV-001"            // string \u2014 right-aligned text
+  rightSubText="Due: Jan 31"     // string \u2014 right sub-text
+  variant="simple"               // 'simple' | 'centered' | 'minimal' | 'branded' | 'logo-left' | 'logo-right' | 'two-column'
+  logo={<PdfImage src="..." />}  // ReactNode \u2014 for logo-left/logo-right
+  background="#18181b"            // string \u2014 background color (branded)
+  titleColor="#fff"               // string \u2014 title text color
+  address="123 Main St"          // string \u2014 for two-column variant
+  phone="+1-555-0100"            // string
+  email="hello@acme.com"         // string
+  fixed                          // boolean \u2014 repeat on every page
 />
 \`\`\`
 
@@ -3585,10 +3692,19 @@ import { PageHeader } from '@/components/pdfx/page-header/pdfx-page-header';
 \`\`\`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
+  leftText="\xA9 2024 Acme Corp"   // string
+  centerText="Confidential"      // string
+  rightText="Page 1 of 1"        // string
+  variant="simple"               // 'simple' | 'centered' | 'branded' | 'minimal' | 'three-column' | 'detailed'
+  background="#18181b"            // string
+  textColor="#fff"                // string
+  address="123 Main St"          // string \u2014 for three-column/detailed
+  phone="+1-555-0100"            // string
+  email="hello@acme.com"         // string
+  website="https://acme.com"     // string
+  fixed                          // boolean \u2014 repeat on every page
+  sticky                         // boolean \u2014 absolute position at page bottom
+  pagePadding={40}               // number \u2014 offset for sticky positioning
 />
 \`\`\`
 
@@ -3598,8 +3714,10 @@ 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'
+  variant="success"  // 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'info' | 'outline'
   size="md"          // 'sm' | 'md' | 'lg'
+  background="#000"  // string \u2014 override background
+  color="#fff"       // string \u2014 override text color
 />
 // OR
 <Badge variant="success">PAID</Badge>
@@ -3610,12 +3728,17 @@ import { Badge } from '@/components/pdfx/badge/pdfx-badge';
 import { KeyValue } from '@/components/pdfx/key-value/pdfx-key-value';
 <KeyValue
   items={[
-    { label: 'Invoice #', value: 'INV-001' },
-    { label: 'Due Date', value: 'Jan 31, 2025' },
+    { key: 'Invoice #', value: 'INV-001' },
+    { key: 'Due Date', value: 'Jan 31, 2025', valueColor: 'destructive' },
   ]}
-  columns={2}         // 1 | 2 | 3 \u2014 default: 1
-  labelWidth={80}     // number in pt
-  colon               // boolean \u2014 adds colon after label
+  direction="horizontal"  // 'horizontal' | 'vertical' \u2014 default: 'horizontal'
+  divided                  // boolean \u2014 dividers between rows
+  size="md"                // 'sm' | 'md' | 'lg' \u2014 default: 'md'
+  labelFlex={1}            // number \u2014 flex ratio for label column
+  labelColor="#666"        // string
+  valueColor="#000"        // string
+  boldValue                // boolean \u2014 bold all values
+  noWrap                   // boolean
 />
 \`\`\`
 
@@ -3625,7 +3748,7 @@ 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={[...]} />
+  <Table variant="grid">...</Table>
 </KeepTogether>
 \`\`\`
 
@@ -3633,74 +3756,102 @@ import { KeepTogether } from '@/components/pdfx/keep-together/pdfx-keep-together
 \`\`\`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
+  src="https://example.com/image.png"  // string | { uri, method?, headers?, body? } \u2014 required
+  variant="default"     // 'default' | 'full-width' | 'thumbnail' | 'avatar' | 'cover' | 'bordered' | 'rounded'
+  width={200}           // number | string in pt
+  height={150}          // number | string \u2014 auto from aspect ratio if omitted
+  fit="contain"         // 'cover' | 'contain' | 'fill' | 'none' \u2014 default varies by variant
+  position="50% 50%"   // string \u2014 object-position
+  caption="Figure 1"   // string \u2014 centered below image
+  aspectRatio={16/9}    // number \u2014 compute height from width
+  borderRadius={4}      // number
+  noWrap                // boolean \u2014 default: true
 />
 \`\`\`
 
-### Graph
+### PdfGraph
 \`\`\`tsx
-import { Graph } from '@/components/pdfx/graph/pdfx-graph';
-<Graph
-  type="bar"          // 'bar' | 'line' | 'pie' | 'donut'
+import { PdfGraph } from '@/components/pdfx/graph/pdfx-graph';
+<PdfGraph
+  variant="bar"         // 'bar' | 'horizontal-bar' | 'line' | 'area' | '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
+  title="Revenue"       // string
+  subtitle="FY2024"     // string
+  xLabel="Quarter"      // string \u2014 x-axis label
+  yLabel="Revenue ($)"  // string \u2014 y-axis label
+  width={420}           // number \u2014 default: 420 (or auto with fullWidth)
+  height={260}          // number \u2014 default: 260
+  fullWidth             // boolean \u2014 auto-calculates width from page margins
+  containerPadding={12} // number \u2014 for fullWidth: outer container padding
+  wrapperPadding={12}   // number \u2014 for fullWidth: wrapper padding
+  colors={['#18181b', '#71717a']}  // string[] \u2014 color palette
+  showValues            // boolean \u2014 show numeric labels on bars/points
+  showGrid              // boolean \u2014 default: true
+  legend="bottom"       // 'bottom' | 'right' | 'none' \u2014 default: 'bottom'
+  centerLabel="$1.2M"  // string \u2014 for donut: text in center hole
+  showDots              // boolean \u2014 default: true (line/area only)
+  smooth                // boolean \u2014 bezier curves (line/area only)
+  yTicks={5}            // number \u2014 Y-axis tick count
+  noWrap                // boolean \u2014 default: true
 />
 \`\`\`
+Multi-series data: \`data={[{ name: 'Series A', data: [...] }, { name: 'Series B', data: [...] }]}\`
+Graph width utilities: \`getGraphWidth(theme, opts?)\`, \`GRAPH_SAFE_WIDTHS\`, \`A4_WIDTH\` are exported.
 
-### PageNumber
+### PdfPageNumber
 \`\`\`tsx
-import { PageNumber } from '@/components/pdfx/page-number/pdfx-page-number';
-<PageNumber
-  format="Page {current} of {total}"  // string template
-  size="sm"
-  align="right"
+import { PdfPageNumber } from '@/components/pdfx/page-number/pdfx-page-number';
+<PdfPageNumber
+  format="Page {page} of {total}"  // string \u2014 use {page} and {total} placeholders
+  align="center"       // 'left' | 'center' | 'right' \u2014 default: 'center'
+  size="sm"            // 'xs' | 'sm' | 'md' \u2014 default: 'sm'
+  fixed                // boolean \u2014 repeats on every page
+  muted                // boolean \u2014 default: true, uses mutedForeground color
 />
 \`\`\`
 
-### Watermark
+### PdfWatermark
 \`\`\`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
+  opacity={0.15}        // number 0\u20131 \u2014 default: 0.15
+  fontSize={60}         // number \u2014 default: 60
+  color="mutedForeground" // string \u2014 default: 'mutedForeground' (theme key or hex)
+  angle={-45}           // number in degrees \u2014 default: -45
+  position="center"     // 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  fixed                 // boolean \u2014 default: true (repeats on every page)
 />
 \`\`\`
 
-### QRCode
+### PdfQRCode
 \`\`\`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'
+  size={100}                    // number \u2014 default: 100
+  color="#000000"               // string \u2014 default: '#000000'
+  backgroundColor="#ffffff"     // string \u2014 default: '#ffffff'
+  errorLevel="M"               // 'L' | 'M' | 'Q' | 'H' \u2014 default: 'M'
+  margin={2}                    // number \u2014 quiet zone modules \u2014 default: 2
+  caption="Scan me"             // string \u2014 text below QR code
 />
 \`\`\`
 
-### Alert
+### PdfAlert
 \`\`\`tsx
-import { Alert } from '@/components/pdfx/alert/pdfx-alert';
-<Alert
-  variant="info"      // 'info' | 'success' | 'warning' | 'error'
-  title="Note"        // string \u2014 optional bold title
+import { PdfAlert } from '@/components/pdfx/alert/pdfx-alert';
+<PdfAlert
+  variant="info"       // 'info' | 'success' | 'warning' | 'error' \u2014 default: 'info'
+  title="Note"         // string \u2014 optional bold title
+  showIcon             // boolean \u2014 default: true
+  showBorder           // boolean \u2014 default: true (left border)
 >
   This is an informational note.
-</Alert>
+</PdfAlert>
 \`\`\`
 
 ---
@@ -3713,20 +3864,18 @@ 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
+- invoice-classic \u2014 Professional with logo-left header and zebra-striped grid table
+- invoice-minimal \u2014 Clean stripped-down, typography-focused layout
+- invoice-modern \u2014 Full-width banner header, horizontal meta strip
+- invoice-corporate \u2014 Formal layout with purchase order fields and signatures
+- invoice-creative \u2014 Accent sidebar, vibrant color highlights
+- invoice-consultant \u2014 Hourly rate breakdown, project summary
 
 ### 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
+- report-financial \u2014 KPI cards, trend chart, delivery table
+- report-marketing \u2014 Channel performance, acquisition trendline
+- report-operations \u2014 SLA health, throughput trends, risk tracking
+- report-security \u2014 Vulnerability trend tracking, remediation table
 
 Blocks are added as full React components in your project. Customize all content props.
 
@@ -3811,6 +3960,18 @@ npx pdfx-cli@latest skills init --platform antigravity # .antigravity/context.md
 
 ---
 
+## Component Naming Convention
+
+PDFx uses a \`Pdf\` prefix when the component name collides with an existing widely-used React
+or @react-pdf/renderer export:
+
+Prefixed (10): PdfAlert, PdfCard, PdfForm, PdfGraph, PdfImage, PdfList, PdfPageNumber, PdfQRCode, PdfSignatureBlock, PdfWatermark
+Unprefixed (14): Badge, DataTable, Divider, Heading, KeepTogether, KeyValue, Link, PageBreak, PageFooter, PageHeader, Section, Stack, Table, Text
+
+When importing, always use the exact name shown in each component section above.
+
+---
+
 ## Common patterns
 
 ### Full invoice from scratch
@@ -3818,7 +3979,7 @@ npx pdfx-cli@latest skills init --platform antigravity # .antigravity/context.md
 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 { Table, TableHeader, TableBody, TableRow, TableCell } 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';
@@ -3830,24 +3991,30 @@ export function InvoiceDoc() {
         <Heading level={1}>Invoice #INV-001</Heading>
         <KeyValue
           items={[
-            { label: 'Date', value: 'Jan 1, 2025' },
-            { label: 'Due', value: 'Jan 31, 2025' },
+            { key: 'Date', value: 'Jan 1, 2025' },
+            { key: 'Due', value: 'Jan 31, 2025' },
           ]}
-          columns={2}
+          direction="horizontal"
         />
         <Divider spacing="md" />
-        <Table
-          headers={['Description', 'Qty', 'Total']}
-          rows={[
-            ['Design System', '1', '$4,800'],
-            ['Development', '2', '$9,600'],
-          ]}
-          striped
-          bordered
-          columnWidths={[3, 1, 1]}
-        />
+        <Table variant="grid" zebraStripe>
+          <TableHeader>
+            <TableRow>
+              <TableCell header width="60%">Description</TableCell>
+              <TableCell header align="center">Qty</TableCell>
+              <TableCell header align="right">Total</TableCell>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>Design System</TableCell>
+              <TableCell align="center">1</TableCell>
+              <TableCell align="right">$4,800</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
         <Badge label="PAID" variant="success" />
-        <PageFooter left="Acme Corp" right="Page 1 of 1" bordered />
+        <PageFooter leftText="Acme Corp" rightText="Page 1 of 1" />
       </Page>
     </Document>
   );
@@ -3859,7 +4026,7 @@ export function InvoiceDoc() {
 // Wrap anything that must stay together across page boundaries
 <KeepTogether>
   <Heading level={3}>Q3 Summary</Heading>
-  <Table headers={['Metric', 'Value']} rows={data} />
+  <DataTable columns={columns} data={data} variant="grid" />
 </KeepTogether>
 \`\`\`
 
@@ -3877,7 +4044,7 @@ export async function GET(req: Request) {
   return new Response(buf, {
     headers: {
       'Content-Type': 'application/pdf',
-      'Content-Disposition': \`inline; filename="invoice-\${id}.pdf"\`,
+      'Content-Disposition': \\\`inline; filename="invoice-\\\${id}.pdf"\\\`,
     },
   });
 }
@@ -3918,6 +4085,7 @@ export async function GET(req: Request) {
 - 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
+- DO NOT return HTML elements from DataTable render/renderFooter \u2014 PDF elements only
 
 ---
 

package/dist/mcp/index.js

@@ -570,8 +570,21 @@ async function getAuditChecklist() {
     \`\`\`
 
     ### "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.
+    \`@react-pdf/renderer\` renders synchronously. Hooks that depend on browser APIs or
+    async side effects do not work in the PDF render path.
+
+    **Do NOT use inside a PDFx component:**
+    - \`useEffect\` / \`useLayoutEffect\` — no browser lifecycle in PDF rendering
+    - \`useRef\` for DOM nodes — no DOM exists in the PDF render tree
+    - Any hook that calls browser globals (\`window\`, \`document\`, \`navigator\`)
+
+    **These ARE valid inside PDFx components:**
+    - PDFx framework hooks: \`usePdfxTheme()\`, \`useSafeMemo()\`
+    - Custom hooks that are pure functions with no browser-API dependencies
+    - Data passed down as props from a parent client component
+
+    If you see this error in a wrapper component you wrote, move the browser hook
+    to the nearest client component and pass the result down as a prop.
 
     ### "Text strings must be rendered inside \`<Text>\` component"
     Wrap all string literals in \`<Text>\` from \`@react-pdf/renderer\`:
@@ -771,7 +784,7 @@ async function getComponent(args) {
   const primaryContent = item.files[0]?.content ?? "";
   const primaryPath = item.files[0]?.path ?? "";
   const exportNames = extractAllExportNames(primaryContent);
-  const mainExport = extractExportName(primaryContent);
+  const mainExport = extractExportName(primaryContent, args.component);
   const exportSection = exportNames.length > 0 ? dedent4`
           ## Exports
           **Main component export:** \`${mainExport ?? exportNames[0]}\`
@@ -816,11 +829,18 @@ async function getComponent(args) {
     ${fileSources}
   `);
 }
-function extractExportName(source) {
+function extractExportName(source, componentName) {
   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;
+  const matches = [...source.matchAll(/export\s+function\s+([A-Z][A-Za-z0-9]*)/g)];
+  const names = matches.map((m) => m[1]).filter(Boolean);
+  if (names.length === 0) return null;
+  if (!componentName) return names[0];
+  const norm = componentName.replace(/-/g, "").toLowerCase();
+  const exact = names.find((n) => n.toLowerCase() === norm);
+  if (exact) return exact;
+  const suffix = names.find((n) => n.toLowerCase().endsWith(norm));
+  if (suffix) return suffix;
+  return names[0];
 }
 function extractAllExportNames(source) {
   const seen = /* @__PURE__ */ new Set();
@@ -1029,7 +1049,7 @@ async function getInstallation(args) {
     | 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 |
+    | "Invalid hook call" | Browser-only hooks (\`useEffect\`, \`useRef\` for DOM) don't work in the PDF render path — move them to a parent client component and pass the result as a prop. PDFx framework hooks (\`usePdfxTheme\`, \`useSafeMemo\`) are valid inside PDF components. |
 
     ---
     Next: call \`get_audit_checklist\` to verify your setup is correct.
@@ -1153,14 +1173,13 @@ async function getTheme(args) {
 
     ## Usage in Components
     \`\`\`tsx
-    // Access theme values in a PDFx component
-    import type { PdfxTheme } from '@pdfx/shared';
-
-    interface Props {
-      theme: PdfxTheme;
-    }
+    // Access theme values in a PDFx component via the usePdfxTheme hook.
+    // @pdfx/shared is workspace-only — do NOT import from it in your components.
+    import { View, Text } from '@react-pdf/renderer';
+    import { usePdfxTheme } from '../lib/pdfx-theme-context';
 
-    export function MyComponent({ theme }: Props) {
+    export function MyComponent() {
+      const theme = usePdfxTheme();
       return (
         <View style={{ backgroundColor: theme.colors.background }}>
           <Text style={{ color: theme.colors.foreground, fontSize: theme.typography.body.fontSize }}>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfx-cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CLI for PDFx components",
   "type": "module",
   "bin": {