@pixldocs/canvas-renderer 0.3.3 → 0.3.4

package/README.md

@@ -1,6 +1,6 @@
 # @pixldocs/canvas-renderer
 
-React component + imperative API for rendering Pixldocs templates client-side. No server needed.
+Client-side template renderer for Pixldocs — render templates in any web app with 1:1 visual parity with the Pixldocs editor. No server round-trip needed for previews.
 
 ## Installation
 
@@ -8,57 +8,92 @@ React component + imperative API for rendering Pixldocs templates client-side. N
 npm install @pixldocs/canvas-renderer fabric react react-dom
 ```
 
-## Quick Start — React Component
+> **Private package**: Add `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` to your `.npmrc` and configure `NPM_TOKEN` as a build secret.
 
-### Mode 1: Pre-resolved config
+---
+
+## Two Rendering Approaches
+
+### Approach A: Live Canvas (interactive)
+
+Renders a visible `<canvas>` element in your page. Best for editors, interactive tools, or when you need real-time canvas manipulation.
 
 ```tsx
 import { PixldocsPreview } from '@pixldocs/canvas-renderer';
 
-function App() {
-  return (
-    <PixldocsPreview
-      config={templateConfig}
-      pageIndex={0}
-      imageProxyUrl="https://your-project.supabase.co/functions/v1/image-proxy"
-      onReady={() => console.log('Rendered!')}
-    />
-  );
-}
+<PixldocsPreview
+  templateId="your-template-id"
+  formSchemaId="your-schema-id"
+  sectionState={sectionState}
+  supabaseUrl="https://xxx.supabase.co"
+  supabaseAnonKey="eyJ..."
+  pageIndex={0}
+  onReady={() => console.log('Canvas ready')}
+/>
 ```
 
-### Mode 2: Auto-resolve from database (recommended)
+**Pros**: Real-time updates, no re-render flicker  
+**Cons**: Heavier DOM footprint, canvas stays in memory
+
+### Approach B: Hidden Canvas → Image (recommended for previews)
 
-Pass the same data you'd send to the server API — the component fetches
-the template, resolves repeatable sections, applies themes, and renders.
+Renders off-screen using a hidden canvas, captures the result as a data URL, and displays it as a lightweight `<img>`. Best for preview panels, template pickers, and multi-page views.
 
 ```tsx
-import { PixldocsPreview } from '@pixldocs/canvas-renderer';
+import { useState, useEffect } from 'react';
+import { PixldocsRenderer } from '@pixldocs/canvas-renderer';
 
-function App() {
-  const sectionState = {
-    section_abc123: { full_name: 'John Doe', photo: 'https://...' },
-    section_def456: [
-      { label: 'Date of Birth', value: '1995-08-15' },
-      { label: 'Religion', value: 'Hindu' },
-    ],
-  };
+const renderer = new PixldocsRenderer({
+  supabaseUrl: 'https://xxx.supabase.co',
+  supabaseAnonKey: 'eyJ...',
+});
+
+function TemplatePreview({ templateId, formSchemaId, sectionState, themeId }) {
+  const [pages, setPages] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    async function render() {
+      setLoading(true);
+      try {
+        const results = await renderer.renderFromForm({
+          templateId,
+          formSchemaId,
+          sectionState,
+          themeId,
+        });
+        if (!cancelled) setPages(results);
+      } catch (err) {
+        console.error('Render failed:', err);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+    render();
+    return () => { cancelled = true; };
+  }, [templateId, formSchemaId, sectionState, themeId]);
+
+  if (loading) return <div>Generating preview...</div>;
 
   return (
-    <PixldocsPreview
-      templateId="dc3fbb17-b671-47cb-a4cf-643a10251fb2"
-      formSchemaId="b04cd362-a0ef-438d-a7a3-0e8560a709ce"
-      sectionState={sectionState}
-      supabaseUrl="https://xxx.supabase.co"
-      supabaseAnonKey="eyJ..."
-      onReady={() => console.log('Rendered!')}
-      onError={(err) => console.error(err)}
-    />
+    <div>
+      {pages.map((page, i) => (
+        <img key={i} src={page.dataUrl} width={page.width} height={page.height} alt={`Page ${i + 1}`} />
+      ))}
+    </div>
   );
 }
 ```
 
-### Props
+**Pros**: Lightweight DOM (just `<img>` tags), canvas is disposed after capture, fast for multi-page  
+**Cons**: Not interactive, requires re-render to update
+
+---
+
+## API Reference
+
+### `PixldocsPreview` (React Component)
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -66,67 +101,69 @@ function App() {
 | `templateId` | `string` | — | Template UUID (Mode 2) |
 | `formSchemaId` | `string` | — | Form schema UUID (Mode 2) |
 | `sectionState` | `SectionFormState` | — | V2 section state data (Mode 2) |
-| `themeId` | `string` | `'default'` | Theme variant ID (Mode 2) |
+| `themeId` | `string` | `'default'` | Theme variant ID |
 | `supabaseUrl` | `string` | — | Supabase URL (Mode 2) |
 | `supabaseAnonKey` | `string` | — | Supabase anon key (Mode 2) |
 | `pageIndex` | `number` | `0` | Page index to render |
 | `zoom` | `number` | auto-fit | Zoom/scale factor |
-| `absoluteZoom` | `boolean` | `false` | Use zoom as-is without auto-fit |
 | `imageProxyUrl` | `string` | — | CORS proxy URL for external images |
-| `className` | `string` | — | CSS class for outer container |
 | `onReady` | `() => void` | — | Called when rendering completes |
 | `onError` | `(error: Error) => void` | — | Called on error |
 
-## Imperative API
-
-### Render from V2 sectionState (primary use case)
-
-Same payload format as the Pixldocs server API (`/render-from-form`):
+### `PixldocsRenderer` (Imperative API)
 
 ```ts
-import { PixldocsRenderer } from '@pixldocs/canvas-renderer';
-
 const renderer = new PixldocsRenderer({
-  supabaseUrl: 'https://xxx.supabase.co',
-  supabaseAnonKey: 'eyJ...',
+  supabaseUrl: string,
+  supabaseAnonKey: string,
+  imageProxyUrl?: string,   // CORS proxy for external images
+  pixelRatio?: number,       // default: 2
 });
+```
 
+#### `renderer.renderFromForm(options)`
+
+Renders all pages from a V2 sectionState payload (same format as the server `/render-from-form` API).
+
+```ts
 const results = await renderer.renderFromForm({
-  templateId: 'dc3fbb17-b671-47cb-a4cf-643a10251fb2',
-  formSchemaId: 'b04cd362-a0ef-438d-a7a3-0e8560a709ce',
-  sectionState: {
-    section_abc: { full_name: 'John' },
-    section_def: [{ label: 'DOB', value: '1995-08-15' }],
-  },
-  themeId: 'default',
+  templateId: 'uuid',
+  formSchemaId: 'uuid',
+  sectionState: { section_abc: { name: 'John' }, section_def: [...] },
+  themeId: 'default',       // optional
+  format: 'png',            // 'png' | 'jpeg' | 'webp'
+  quality: 0.92,            // for jpeg/webp
+  scale: 1,                 // scale multiplier
 });
-
-// results is an array of { dataUrl, width, height } for each page
-for (const page of results) {
-  console.log(page.dataUrl); // data:image/png;base64,...
-}
+// Returns: RenderResult[] — one per page
+// Each: { dataUrl, width, height, pixelWidth, pixelHeight }
 ```
 
-### Render a pre-resolved config
+#### `renderer.render(config, options?)`
+
+Renders a single page from a pre-resolved template config.
 
 ```ts
-const { dataUrl } = await renderer.render(templateConfig);
-const allPages = await renderer.renderAllPages(templateConfig);
+const { dataUrl, width, height } = await renderer.render(templateConfig, { pageIndex: 0 });
 ```
 
-### Render by template ID (simple flat data)
+#### `renderer.renderAllPages(config, options?)`
+
+Renders all pages from a pre-resolved config.
 
 ```ts
-const result = await renderer.renderById('template-uuid', { name: 'John' });
+const pages = await renderer.renderAllPages(templateConfig);
 ```
 
-## Data Resolution Utilities
+### Data Resolution Utilities
+
+Resolve template data without rendering — useful for inspecting configs or building custom pipelines.
 
 ```ts
 import { resolveFromForm, resolveTemplateData } from '@pixldocs/canvas-renderer';
 
-// V2: resolve from sectionState (same as server API)
-const { config } = await resolveFromForm({
+// V2: resolve from sectionState
+const { config, totalPages } = await resolveFromForm({
   templateId: 'uuid',
   formSchemaId: 'uuid',
   sectionState: { ... },
@@ -141,8 +178,14 @@ const { config } = await resolveTemplateData({
 });
 ```
 
+---
+
 ## Peer Dependencies
 
 - `fabric` ^6.0.0
 - `react` ^18.0.0 || ^19.0.0
 - `react-dom` ^18.0.0 || ^19.0.0
+
+## License
+
+UNLICENSED — Private package for Pixldocs ecosystem only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixldocs/canvas-renderer",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Client-side template renderer for Pixldocs — React component + imperative API for rendering templates in any web app",
   "type": "module",
   "main": "dist/index.cjs",