feat: introduce DETECT_FIELDS for automatic detection of flattened fields

.changeset/replace-create-field-with-detect-fields.md

@@ -0,0 +1,15 @@
+---
+"@simplepdf/react-embed-pdf": major
+---
+
+Replaces `createField` with `detectFields` for automatic form field detection. This is a breaking change: the `createField` action and `CreateFieldOptions` type have been removed.
+
+If you are not using `actions.createField(...)` or `sendEvent("CREATE_FIELD", ...)`, you can safely update to this new major version.
+
+```ts
+// Before (removed)
+await actions.createField({ type: "TEXT", page: 1, x: 100, y: 700, width: 200, height: 30 });
+
+// After
+await actions.detectFields();
+```

README.md

@@ -189,7 +189,7 @@ SimplePDF Embed uses a **fully client-side architecture** for PDF processing:
 
 | Limitation                        | Description                                     | Workaround                                                 |
 | --------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
-| **No server-side PDF generation** | Cannot generate PDFs from templates server-side | Use client-side field creation via `createField()`         |
+| **No server-side PDF generation** | Cannot generate PDFs from templates server-side | Use client-side field detection via `detectFields()`       |
 | **No bulk processing**            | Cannot process multiple PDFs in batch           | Process sequentially or use dedicated server-side library  |
 | **No programmatic PDF retrieval** | Cannot get modified PDF as Blob/Base64 in JS    | Use webhooks + server storage for programmatic access      |
 | **No persistent storage**         | PDFs don't persist without user action          | Use `companyIdentifier` for server-side submission storage |
@@ -285,7 +285,7 @@ Currently, page manipulation (add/remove/re-arrange/rotate) is only available th
 | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `goTo`                 | Navigate to a specific page                                                                                |
 | `selectTool`           | Select a tool (`TEXT`, `BOXED_TEXT`, `CHECKBOX`, `PICTURE`, `SIGNATURE`) or `null` for cursor              |
-| `createField`          | Create a field at a specified position                                                                     |
+| `detectFields`         | Automatically detect form fields in the document                                                           |
 | `removeFields`         | Remove fields by ID, by page, or all fields                                                                |
 | `getDocumentContent`   | Extract text content from the document                                                                     |
 | `submit`               | Submit the document (with optional device download)                                                        |

documentation/IFRAME.md

@@ -185,16 +185,8 @@ await sendEvent("GO_TO", { page: 3 });
 // Select a tool
 await sendEvent("SELECT_TOOL", { tool: "TEXT" }); // or "CHECKBOX", "SIGNATURE", "PICTURE", "BOXED_TEXT", null
 
-// Create a field
-await sendEvent("CREATE_FIELD", {
-  type: "TEXT",
-  page: 1,
-  x: 100,
-  y: 700,
-  width: 200,
-  height: 30,
-  value: "Hello World",
-});
+// Detect fields in the document
+await sendEvent("DETECT_FIELDS", {});
 
 // Remove all fields (or specific ones)
 await sendEvent("REMOVE_FIELDS", {}); // Remove all
@@ -290,34 +282,11 @@ Select a drawing tool or return to cursor mode.
 | ------ | ---------------- | -------- | ---------------------------------------------------------------------------------------- |
 | `tool` | `string \| null` | Yes      | `"TEXT"`, `"BOXED_TEXT"`, `"CHECKBOX"`, `"SIGNATURE"`, `"PICTURE"`, or `null` for cursor |
 
-#### CREATE_FIELD
-
-Create a new field on the document.
+#### DETECT_FIELDS
 
-| Field    | Type     | Required | Description                                                           |
-| -------- | -------- | -------- | --------------------------------------------------------------------- |
-| `type`   | `string` | Yes      | `"TEXT"`, `"BOXED_TEXT"`, `"CHECKBOX"`, `"SIGNATURE"`, or `"PICTURE"` |
-| `page`   | `number` | Yes      | Page number (1-indexed)                                               |
-| `x`      | `number` | Yes      | X coordinate (PDF points from left)                                   |
-| `y`      | `number` | Yes      | Y coordinate (PDF points from bottom)                                 |
-| `width`  | `number` | Yes      | Field width in PDF points                                             |
-| `height` | `number` | Yes      | Field height in PDF points                                            |
-| `value`  | `string` | No       | Initial value (see value formats below)                               |
+Automatically detect form fields in the document.
 
-**Value formats by field type:**
-
-- `TEXT` / `BOXED_TEXT`: Plain text content
-- `CHECKBOX`: `"checked"` or `"unchecked"`
-- `PICTURE`: Data URL (base64)
-- `SIGNATURE`: Data URL (base64 image) or plain text (generates a typed signature)
-
-**Response data:**
-
-```json
-{
-  "field_id": "f_kj8n2hd9x3m1p"
-}
-```
+_No data fields required._
 
 #### REMOVE_FIELDS
 

examples/with-playwright-automation/README.md

@@ -1,244 +1,33 @@
 # SimplePDF Editor Automation
 
-Playwright-based CLI tool for programmatically creating and positioning fields in PDF documents using the SimplePDF editor.
-
-## Features
-
-- Create TEXT, BOXED_TEXT, CHECKBOX, SIGNATURE, and PICTURE fields
-- Position fields using PDF standard coordinates (bottom-left origin)
-- Pre-fill field values including typed signatures
-- Browser opens for visual inspection after field creation
+Playwright-based CLI tool for automatically detecting form fields in PDF documents using the SimplePDF editor.
 
 ## Quick Start
 
 ```bash
 npm install
-npx tsx src/index.ts example.config.json
+npx tsx src/index.ts https://example.com/form.pdf
 ```
 
 ## Usage
 
 ```bash
-npx tsx src/index.ts <config.json> [options]
+npx tsx src/index.ts <document> [options]
+
+Arguments:
+  document              URL or local file path to a PDF
 
 Options:
   --company-identifier  Your SimplePDF company identifier (default: embed)
   --help                Show help
 ```
 
-### Using Your Company Identifier
+### Examples
 
 ```bash
-npx tsx src/index.ts config.json --company-identifier mycompany
-```
-
-This connects to `https://mycompany.simplepdf.com`.
-
-## Configuration
-
-Create a JSON configuration file:
-
-```json
-{
-  "document": "https://example.com/document.pdf",
-  "fields": [...]
-}
-```
-
-### Document Source
-
-| Format | Example |
-|--------|---------|
-| URL | `"https://example.com/doc.pdf"` |
-| Local file | `"./documents/form.pdf"` |
-
-## Field Types
-
-### TEXT
-
-Single-line text input.
-
-```json
-{
-  "type": "TEXT",
-  "x": 100,
-  "y": 700,
-  "width": 200,
-  "height": 20,
-  "page": 1,
-  "value": "John Doe"
-}
-```
-
-### BOXED_TEXT
-
-Multi-line text with border.
-
-```json
-{
-  "type": "BOXED_TEXT",
-  "x": 100,
-  "y": 600,
-  "width": 300,
-  "height": 100,
-  "page": 1,
-  "value": "Additional notes here..."
-}
-```
-
-### CHECKBOX
-
-Checkable box. Must be square (equal width/height).
-
-```json
-{
-  "type": "CHECKBOX",
-  "x": 100,
-  "y": 550,
-  "width": 12,
-  "height": 12,
-  "page": 1,
-  "value": true
-}
-```
-
-### SIGNATURE
-
-Signature field with multiple value formats.
-
-```json
-{
-  "type": "SIGNATURE",
-  "x": 100,
-  "y": 450,
-  "width": 200,
-  "height": 60,
-  "page": 1,
-  "value": "John Doe"
-}
-```
-
-**Value formats:**
-
-| Format | Example | Result |
-|--------|---------|--------|
-| Plain text | `"John Doe"` | Typed signature (cursive font) |
-| URL | `"https://example.com/sig.png"` | Drawn signature from image |
-| Data URL | `"data:image/png;base64,..."` | Drawn signature from base64 |
-| Local file | `"./signatures/john.png"` | Drawn signature from file |
-
-### PICTURE
-
-Image field.
-
-```json
-{
-  "type": "PICTURE",
-  "x": 100,
-  "y": 300,
-  "width": 150,
-  "height": 150,
-  "page": 1,
-  "value": "https://example.com/photo.jpg"
-}
-```
-
-**Value formats:** URL, data URL, or local file path.
-
-## Coordinate System
-
-Uses PDF standard coordinates:
-
-```
-┌─────────────────────────────┐
-│                             │ ↑
-│                             │ │
-│         PDF Page            │ │ Y increases
-│                             │ │
-│                             │ │
-└─────────────────────────────┘
-(0,0) ───────────────────────→
-         X increases
-```
-
-- **Origin**: Bottom-left corner of page
-- **Units**: Points (1/72 inch)
-- **Y-axis**: Increases upward
-
-## Examples
-
-### Basic Form Fill
-
-```json
-{
-  "document": "https://cdn.simplepdf.com/simple-pdf/assets/sample.pdf",
-  "fields": [
-    {
-      "type": "TEXT",
-      "x": 72,
-      "y": 700,
-      "width": 200,
-      "height": 14,
-      "page": 1,
-      "value": "John"
-    },
-    {
-      "type": "TEXT",
-      "x": 320,
-      "y": 700,
-      "width": 200,
-      "height": 14,
-      "page": 1,
-      "value": "Doe"
-    },
-    {
-      "type": "SIGNATURE",
-      "x": 72,
-      "y": 100,
-      "width": 200,
-      "height": 60,
-      "page": 1,
-      "value": "John Doe"
-    }
-  ]
-}
-```
-
-### Multi-Page Document
-
-```json
-{
-  "document": "./documents/multi-page.pdf",
-  "fields": [
-    {
-      "type": "TEXT",
-      "x": 72,
-      "y": 700,
-      "width": 200,
-      "height": 14,
-      "page": 1,
-      "value": "Page 1 content"
-    },
-    {
-      "type": "TEXT",
-      "x": 72,
-      "y": 700,
-      "width": 200,
-      "height": 14,
-      "page": 2,
-      "value": "Page 2 content"
-    },
-    {
-      "type": "SIGNATURE",
-      "x": 72,
-      "y": 100,
-      "width": 200,
-      "height": 60,
-      "page": 3,
-      "value": "Final Signature"
-    }
-  ]
-}
+npx tsx src/index.ts https://example.com/form.pdf
+npx tsx src/index.ts ./documents/form.pdf
+npx tsx src/index.ts https://example.com/form.pdf --company-identifier mycompany
 ```
 
 ## How It Works
@@ -247,9 +36,8 @@ The tool uses the SimplePDF editor's iframe postMessage API:
 
 1. Embeds the editor in an iframe
 2. Waits for `DOCUMENT_LOADED` event
-3. Sends `REMOVE_FIELDS` to remove existing fields
-4. Sends `CREATE_FIELD` for each configured field
-5. Leaves browser open for inspection
+3. Sends `DETECT_FIELDS` to automatically detect form fields
+4. Leaves browser open for inspection
 
 ## Requirements