@lucablockltd/ultimate-packaging 1.0.3 → 1.2.0

package/dist/AGENTS_README.md

@@ -6,7 +6,7 @@
 ## Quick Start
 
 ```bash
-npm install PinitS/ultimate-packaging
+npm install @lucablockltd/ultimate-packaging
 ```
 
 Requires `react >= 18.0.0` and `react-dom >= 18.0.0`.
@@ -18,13 +18,13 @@ Requires `react >= 18.0.0` and `react-dom >= 18.0.0`.
 Use `DIE_LINE_LAYOUT` — one component for ALL models. No switch-case needed.
 
 ```tsx
-import { DIE_LINE_LAYOUT, modelList } from "ultimate-packaging";
-import type { DieLineLayoutRef } from "ultimate-packaging";
+import { DIE_LINE_LAYOUT, modelList } from "@lucablockltd/ultimate-packaging";
+import type { DieLineLayoutRef } from "@lucablockltd/ultimate-packaging";
 
 const ref = useRef<DieLineLayoutRef>(null);
 
 // Get default attributes for any model
-const model = modelList.find(m => m.id === "BECF-1010A")!;
+const model = modelList.find((m) => m.id === "BECF-1010A")!;
 
 <DIE_LINE_LAYOUT
   ref={ref}
@@ -33,18 +33,18 @@ const model = modelList.find(m => m.id === "BECF-1010A")!;
   unit="mm"
   mode="DIE_LINE"
   isShowDimensions={true}
-/>
+/>;
 ```
 
 ### DIE_LINE_LAYOUT Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `modelId` | `string` | YES | — | One of: `"BECF-1010A"`, `"BECF-1030A"`, `"BECF-1040A"`, `"BECF-11D01"` |
-| `attributes` | `object` | YES | — | Box dimensions (see Model Attributes below) |
-| `unit` | `"mm" \| "cm" \| "in"` | no | `"mm"` | Display unit for dimension labels |
-| `mode` | `ModelMode` | no | `"DIE_LINE"` | `"DIE_LINE"` = interactive canvas, `"AUTO_LAYOUT"` = raw SVG |
-| `isShowDimensions` | `boolean` | no | `false` | Show dimension annotation lines |
+| Prop               | Type                   | Required | Default      | Description                                                                                            |
+| ------------------ | ---------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| `modelId`          | `string`               | YES      | —            | One of: `"BECF-1010A"`, `"BECF-1030A"`, `"BECF-1040A"`, `"BECF-11D01"`, `"BECF-12101"`, `"BECF-12109"` |
+| `attributes`       | `object`               | YES      | —            | Box dimensions (see Model Attributes below)                                                            |
+| `unit`             | `"mm" \| "cm" \| "in"` | no       | `"mm"`       | Display unit for dimension labels                                                                      |
+| `mode`             | `ModelMode`            | no       | `"DIE_LINE"` | `"DIE_LINE"` = interactive canvas, `"AUTO_LAYOUT"` = raw SVG                                           |
+| `isShowDimensions` | `boolean`              | no       | `false`      | Show dimension annotation lines                                                                        |
 
 ### DIE_LINE_LAYOUT Ref Methods
 
@@ -55,7 +55,10 @@ const ref = useRef<DieLineLayoutRef>(null);
 ref.current.getAttributes(); // → { length: 60, width: 25, ... }
 
 // Export as PNG image
-const blob = await ref.current.exportImage({ isShowDimension: true, originalSize: true });
+const blob = await ref.current.exportImage({
+  isShowDimension: true,
+  originalSize: true,
+});
 
 // Export dimensions as PDF
 const pdf = await ref.current.exportDimension();
@@ -66,68 +69,350 @@ const pdf = await ref.current.exportDimension();
 ## 2. Auto-Layout (Pack Dielines on Paper)
 
 Use `AUTO_LAYOUT` to automatically arrange dieline pieces on paper sheets.
+The engine calculates the optimal rotation and grid placement to maximize pieces per sheet.
 
-```tsx
-import { AUTO_LAYOUT, calculateAutoLayout } from "ultimate-packaging";
-import type { AutoLayoutRef, AutoLayoutConfig, AutoLayoutResult } from "ultimate-packaging";
+### AutoLayoutConfig — Full Reference
 
-const ref = useRef<AutoLayoutRef>(null);
-const [result, setResult] = useState<AutoLayoutResult | null>(null);
+`AutoLayoutConfig` has **3 required fields** and **5 optional print-setting fields**.
+If you omit any optional field, the system uses a sensible default automatically.
+
+```typescript
+interface AutoLayoutConfig {
+  // ─── REQUIRED ───────────────────────────────────────────────
+  papers: AutoLayoutPaper[];  // At least 1 paper size to test
+  model: AutoLayoutModel;     // Which box/bag model and its dimensions
+  quantity: number;            // Total pieces needed (e.g. 1000)
+
+  // ─── OPTIONAL (print settings) ──────────────────────────────
+  // You can omit ALL of these — the system will use defaults.
+  layoutDistance?: number;     // default: 3   — mm gap between piece cut-lines
+  spacing?: number;            // default: 5   — mm margin from paper edges
+  griper?: number;             // default: 10  — mm machine gripper zone
+  colorbarHeight?: number;     // default: 5   — mm height of color test strip
+  isShowColorbar?: boolean;    // default: true — whether to show colorbar
+}
+```
+
+#### Required Field #1: `papers` — Paper sizes to test
+
+An array of paper sizes. The engine will calculate layout for EVERY paper and rank them by efficiency.
+Each paper needs 4 fields — all required:
+
+```typescript
+interface AutoLayoutPaper {
+  paperId: string;      // Unique ID (any string, e.g. "1", "paper-a4", "custom-1")
+  paperName: string;    // Display name (e.g. "20x28\"", "A4", "25x36\"")
+  paperWidth: number;   // Width in millimeters
+  paperHeight: number;  // Height in millimeters
+}
+```
+
+**Common paper sizes (inches → mm, multiply by 25.4):**
+
+| Name     | Inches   | paperWidth (mm) | paperHeight (mm) |
+| -------- | -------- | --------------- | ----------------- |
+| 20x28"   | 20 × 28  | 508             | 711.2             |
+| 25x36"   | 25 × 36  | 635             | 914.4             |
+| 25x12"   | 25 × 12  | 635             | 304.8             |
+| 23x35"   | 23 × 35  | 584.2           | 889               |
+
+**Example:**
+
+```typescript
+const papers: AutoLayoutPaper[] = [
+  { paperId: "1", paperName: '20x28"', paperWidth: 508, paperHeight: 711.2 },
+  { paperId: "2", paperName: '25x36"', paperWidth: 635, paperHeight: 914.4 },
+];
+```
+
+#### Required Field #2: `model` — Which packaging model and its dimensions
+
+```typescript
+interface AutoLayoutModel {
+  modelId: string;                    // Must be one of the supported model IDs (see below)
+  attributes: Record<string, number>; // Dimensions in mm — different per model
+}
+```
+
+**Supported `modelId` values and their required `attributes`:**
+
+| modelId      | Type                    | Required attributes                                              |
+| ------------ | ----------------------- | ---------------------------------------------------------------- |
+| `BECF-1010A` | Tuck End Box Type A     | `length`, `width`, `height`, `glueArea`, `dustFlap`, `tuckFlap`  |
+| `BECF-1030A` | Tuck End Box Type C     | `length`, `width`, `height`, `glueArea`, `dustFlap`, `tuckFlap`  |
+| `BECF-1040A` | Tuck End Box Type B     | `length`, `width`, `height`, `glueArea`, `dustFlap`, `tuckFlap`  |
+| `BECF-11D01` | Standard Box            | `length`, `width`, `height`, `flapHeight`, `glueArea`            |
+| `BECF-12101` | Carton Bag / Shopping Bag Type A | `length`, `width`, `height`, `glueArea`               |
+| `BECF-12109` | Carton Bag / Shopping Bag Type B | `length`, `width`, `height`, `glueArea`               |
+
+**Example — Tuck End Box:**
+
+```typescript
+const model: AutoLayoutModel = {
+  modelId: "BECF-1010A",
+  attributes: {
+    length: 60,     // box length (mm)
+    width: 25,      // box width (mm)
+    height: 100,    // box height (mm)
+    glueArea: 15,   // glue flap width (mm)
+    dustFlap: 15,   // dust flap extension (mm)
+    tuckFlap: 15,   // tuck flap height (mm)
+  },
+};
+```
+
+**Example — Standard Box:**
+
+```typescript
+const model: AutoLayoutModel = {
+  modelId: "BECF-11D01",
+  attributes: {
+    length: 100,
+    width: 50,
+    height: 150,
+    flapHeight: 50,
+    glueArea: 13,
+  },
+};
+```
+
+**Example — Carton Bag:**
+
+```typescript
+const model: AutoLayoutModel = {
+  modelId: "BECF-12101",
+  attributes: {
+    length: 100,    // A — front/back panel width (mm)
+    width: 50,      // B — side panel / gusset (mm)
+    height: 150,    // C — bag body height (mm)
+    glueArea: 13,   // glue flap width (mm)
+  },
+};
+```
 
+**Tip:** You can use pre-defined default attributes instead of hardcoding:
+
+```typescript
+import {
+  BECF_1010A_DEFAULT_ATTRIBUTES,
+  BECF_12101_DEFAULT_ATTRIBUTES,
+} from "@lucablockltd/ultimate-packaging";
+
+const model: AutoLayoutModel = {
+  modelId: "BECF-1010A",
+  attributes: { ...BECF_1010A_DEFAULT_ATTRIBUTES },
+};
+```
+
+#### Required Field #3: `quantity` — Total pieces needed
+
+A positive integer. The engine calculates how many sheets are needed to produce this quantity.
+
+```typescript
+quantity: 1000  // need 1000 pieces total
+```
+
+#### Optional Print Settings (all have defaults)
+
+These 5 fields control the printing press layout. **You can omit any or all of them.**
+
+| Field            | Type      | Default | What it does                                                                                     |
+| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `layoutDistance` | `number`  | `3`     | Gap between piece cut-lines in mm. Creates an offset contour around each piece (half on each side). Set to `0` for pieces touching edge-to-edge. |
+| `spacing`        | `number`  | `5`     | Margin from all paper edges in mm. Reserved border where no pieces are placed.                   |
+| `griper`         | `number`  | `10`    | Machine gripper zone depth in mm. Area reserved for the printing press feed mechanism. Placed on the bottom edge (landscape) or left edge (portrait). |
+| `colorbarHeight` | `number`  | `5`     | Height of the color test strip in mm. A row of colored squares for print registration, placed on the opposite side of the gripper. |
+| `isShowColorbar` | `boolean` | `true`  | Whether to show the colorbar. If `false`, `colorbarHeight` is ignored and that space becomes usable for pieces. |
+
+### Minimal Config Example (only required fields)
+
+This is the **simplest possible config** — all print settings use defaults:
+
+```tsx
 const config: AutoLayoutConfig = {
   papers: [
-    { paperId: "1", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 },
-    { paperId: "2", paperName: "25x36\"", paperWidth: 635, paperHeight: 914.4 },
+    { paperId: "1", paperName: '20x28"', paperWidth: 508, paperHeight: 711.2 },
   ],
   model: {
     modelId: "BECF-1010A",
     attributes: { length: 60, width: 25, height: 100, glueArea: 15, dustFlap: 15, tuckFlap: 15 },
   },
   quantity: 1000,
-  layoutDistance: 3,     // mm gap between pieces (offset contour)
-  spacing: 5,           // mm margin on sides
-  griper: 10,           // mm machine gripper zone
-  colorbarHeight: 5,    // mm colorbar strip height
+  // layoutDistance → defaults to 3
+  // spacing       → defaults to 5
+  // griper        → defaults to 10
+  // colorbarHeight → defaults to 5
+  // isShowColorbar → defaults to true
+};
+```
+
+### Full Config Example (all fields explicit)
+
+```tsx
+const config: AutoLayoutConfig = {
+  papers: [
+    { paperId: "1", paperName: '20x28"', paperWidth: 508, paperHeight: 711.2 },
+    { paperId: "2", paperName: '25x36"', paperWidth: 635, paperHeight: 914.4 },
+  ],
+  model: {
+    modelId: "BECF-1010A",
+    attributes: {
+      length: 60,
+      width: 25,
+      height: 100,
+      glueArea: 15,
+      dustFlap: 15,
+      tuckFlap: 15,
+    },
+  },
+  quantity: 1000,
+  layoutDistance: 3,
+  spacing: 5,
+  griper: 10,
+  colorbarHeight: 5,
   isShowColorbar: true,
 };
+```
+
+### Using the AUTO_LAYOUT Component (React)
+
+```tsx
+import { AUTO_LAYOUT } from "@lucablockltd/ultimate-packaging";
+import type {
+  AutoLayoutRef,
+  AutoLayoutConfig,
+  AutoLayoutResult,
+} from "@lucablockltd/ultimate-packaging";
+
+const ref = useRef<AutoLayoutRef>(null);
+const [result, setResult] = useState<AutoLayoutResult | null>(null);
 
-<AUTO_LAYOUT ref={ref} config={config} onResult={setResult} />
+<AUTO_LAYOUT ref={ref} config={config} onResult={setResult} />;
 ```
 
 ### AUTO_LAYOUT Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `config` | `AutoLayoutConfig \| null` | YES | Layout configuration (null = no render) |
-| `onResult` | `(result: AutoLayoutResult \| null) => void` | no | Called when layout is calculated |
-| `onModifiedPapers` | `(papers: AutoLayoutPaperResult[]) => void` | no | Called when user modifies layout manually |
+| Prop               | Type                                         | Required | Default          | Description                                                                                                       |
+| ------------------ | -------------------------------------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `config`           | `AutoLayoutConfig \| null`                   | YES      | —                | Layout configuration. Pass `null` to clear/hide the layout.                                                       |
+| `onResult`         | `(result: AutoLayoutResult \| null) => void` | no       | —                | Callback fired when layout calculation completes. Receives the full result object.                                |
+| `onModifiedPapers` | `(papers: AutoLayoutPaperResult[]) => void`  | no       | —                | Callback fired when user manually drags/modifies piece positions on the layout.                                   |
+| `isShowSummary`    | `boolean`                                    | no       | `true`           | Show/hide the summary stats panel above each paper (pieces/sheet, waste %, etc.)                                  |
+| `isShowAction`     | `AutoLayoutAction[]`                         | no       | all actions shown | Which action buttons to show. Values: `"EXPORT_SHEET"`, `"EXPORT_PDF"`, `"MODIFY_LAYOUT"`. Omit to show all.     |
 
 ### AUTO_LAYOUT Ref Methods
 
+Access these via `ref.current` after the component mounts:
+
 ```tsx
-// Get calculation result
-ref.current.getResult(); // → AutoLayoutResult
+const ref = useRef<AutoLayoutRef>(null);
+
+// 1. Get the full calculation result
+const result = ref.current.getResult();
+// → AutoLayoutResult | null
 
-// Export layout image (PNG) for specific paper
-const png = await ref.current.exportImage(0); // paper index 0
+// 2. Export a specific paper's layout as PNG image
+const pngBlob = await ref.current.exportImage(0); // 0 = first paper index
+// → Blob (image/png)
 
-// Export layout as PDF
-const pdf = await ref.current.exportPdf(0);
+// 3. Export a specific paper's layout as PDF
+const pdfBlob = await ref.current.exportPdf(0);
+// → Blob (application/pdf)
 
-// Get packed result with dieline + layout image files
+// 4. Export the dieline pattern as PNG
+const dielineBlob = await ref.current.exportDielineImage();
+// → Blob (image/png)
+
+// 5. Get packed result — includes images as File objects (useful for upload/FormData)
 const packed = await ref.current.getPackedResult(0);
-// → { ...paperResult, quantity, dielineFile: File, layoutFile: File }
+// → AutoLayoutPackedResult {
+//     ...all AutoLayoutPaperResult fields,
+//     quantity: number,
+//     dielineFile: File,  // dieline pattern PNG
+//     layoutFile: File,   // layout arrangement PNG
+//   }
 ```
 
-### Programmatic Calculation (No UI)
+### Programmatic Calculation (No UI / No React)
+
+Use `calculateAutoLayout()` to compute layout without rendering any component.
+Same config, same result — just no visual output.
 
 ```tsx
-import { calculateAutoLayout } from "ultimate-packaging";
+import { calculateAutoLayout } from "@lucablockltd/ultimate-packaging";
+import type { AutoLayoutConfig, AutoLayoutResult } from "@lucablockltd/ultimate-packaging";
+
+const config: AutoLayoutConfig = {
+  papers: [
+    { paperId: "A", paperName: '20x28"', paperWidth: 508, paperHeight: 711.2 },
+    { paperId: "B", paperName: '25x36"', paperWidth: 635, paperHeight: 914.4 },
+  ],
+  model: {
+    modelId: "BECF-1010A",
+    attributes: { length: 60, width: 25, height: 100, glueArea: 15, dustFlap: 15, tuckFlap: 15 },
+  },
+  quantity: 1000,
+  // print settings are optional — defaults will be used
+};
+
+const result: AutoLayoutResult = calculateAutoLayout(config);
+
+// Result structure:
+// result.recommendedPaperId  → "B" (best paper by least total area)
+// result.quantity             → 1000
+// result.totalProduced        → 1008 (may exceed quantity due to full sheets)
+// result.totalSheets          → total sheets across all papers
+// result.remainingNeeded      → 0 (if all produced)
+// result.papers               → AutoLayoutPaperResult[] (one per paper, sorted best-first)
+```
+
+### AutoLayoutResult — Output Reference
+
+```typescript
+interface AutoLayoutResult {
+  papers: AutoLayoutPaperResult[];  // Results per paper size, sorted by efficiency (best first)
+  quantity: number;                  // Original requested quantity
+  totalProduced: number;             // Total pieces produced (may exceed quantity)
+  totalSheets: number;               // Total sheets needed across all papers
+  remainingNeeded: number;           // Shortfall (0 if quantity is met)
+  recommendedPaperId: string | null; // paperId of the most efficient paper (least total area)
+}
 
-const result = calculateAutoLayout(config);
-// → AutoLayoutResult { papers, quantity, totalProduced, totalSheets, remainingNeeded, recommendedPaperId }
+interface AutoLayoutPaperResult {
+  paperId: string;              // Matches the input paper's paperId
+  paperName: string;            // Display name
+  paperWidth: number;           // mm
+  paperHeight: number;          // mm
+  producedPerSheet: number;     // How many pieces fit on ONE sheet
+  totalSheets: number;          // Sheets needed for the requested quantity
+  totalProduced: number;        // producedPerSheet × totalSheets
+  excessCount: number;          // Overproduction beyond quantity
+  wastePercent: number;         // Unused paper area percentage (0–100)
+  independentSheets: number;    // Sheets needed if ONLY this paper is used
+  independentTotalArea: number; // Total paper area in mm² if only this paper
+  placements: AutoLayoutPlacement[]; // Position of each piece on the sheet
+  gripperSide: GripperSide;     // Which edge the gripper is on
+}
+
+interface AutoLayoutPlacement {
+  x: number;         // mm from paper left edge
+  y: number;         // mm from paper top edge
+  rotation: number;  // 0 | 90 | 180 | 270 degrees
+}
+
+type GripperSide = "top" | "bottom" | "left" | "right";
+// Automatically determined: landscape paper → "bottom", portrait → "left"
 ```
 
+### Layout Algorithm Summary
+
+1. The engine tries all 4 rotations (0°, 90°, 180°, 270°) for each piece on each paper
+2. For each rotation, it packs pieces in a grid within the **usable bounds**
+3. **Usable bounds** = paper area minus: `spacing` (all edges) + `griper` (one edge) + `colorbarHeight` (opposite edge)
+4. The rotation that fits the **most pieces** wins
+5. Papers are sorted by `independentTotalArea` (ascending) — the paper that uses the least total area to fulfill quantity is ranked #1
+6. `recommendedPaperId` = the #1 ranked paper
+
 ---
 
 ## 3. Available Models & Attributes
@@ -135,13 +420,13 @@ const result = calculateAutoLayout(config);
 ### Get All Models
 
 ```tsx
-import { modelList } from "ultimate-packaging";
+import { modelList } from "@lucablockltd/ultimate-packaging";
 
-modelList.forEach(model => {
-  console.log(model.id);         // "BECF-1010A"
-  console.log(model.nameEN);     // "TUCK END BOXES TYPE A"
-  console.log(model.nameTH);     // "กล่องฝาเสียบ ก้นเสียบ A"
-  console.log(model.dimension);  // ["DIE_LINE"]
+modelList.forEach((model) => {
+  console.log(model.id); // "BECF-1010A"
+  console.log(model.nameEN); // "TUCK END BOXES TYPE A"
+  console.log(model.nameTH); // "กล่องฝาเสียบ ก้นเสียบ A"
+  console.log(model.dimension); // ["DIE_LINE"]
   console.log(model.attributes); // { length: 60, width: 25, ... }
 });
 ```
@@ -152,36 +437,57 @@ modelList.forEach(model => {
 
 ```typescript
 interface TuckEndBoxAttributes {
-  length: number;    // box length (mm)
-  width: number;     // box width (mm)
-  height: number;    // box height (mm)
-  glueArea: number;  // glue flap width (mm)
-  dustFlap: number;  // dust flap extension (mm)
-  tuckFlap: number;  // tuck flap height (mm)
+  length: number; // box length (mm)
+  width: number; // box width (mm)
+  height: number; // box height (mm)
+  glueArea: number; // glue flap width (mm)
+  dustFlap: number; // dust flap extension (mm)
+  tuckFlap: number; // tuck flap height (mm)
 }
 ```
 
-| Model | length | width | height | glueArea | dustFlap | tuckFlap |
-|-------|--------|-------|--------|----------|----------|----------|
-| BECF-1010A | 60 | 25 | 100 | 15 | 15 | 15 |
-| BECF-1030A | 105 | 50 | 155 | 15 | 25 | 14 |
-| BECF-1040A | 56 | 56 | 150 | 15 | 30 | 14 |
+| Model      | length | width | height | glueArea | dustFlap | tuckFlap |
+| ---------- | ------ | ----- | ------ | -------- | -------- | -------- |
+| BECF-1010A | 60     | 25    | 100    | 15       | 15       | 15       |
+| BECF-1030A | 105    | 50    | 155    | 15       | 25       | 14       |
+| BECF-1040A | 56     | 56    | 150    | 15       | 30       | 14       |
 
 #### Standard Box (BECF-11D01)
 
 ```typescript
 interface StandardBoxAttributes {
-  length: number;     // box length (mm)
-  width: number;      // box width (mm)
-  height: number;     // box height (mm)
+  length: number; // box length (mm)
+  width: number; // box width (mm)
+  height: number; // box height (mm)
   flapHeight: number; // top/bottom flap height (mm)
-  glueArea: number;   // glue flap width (mm)
+  glueArea: number; // glue flap width (mm)
 }
 ```
 
-| Model | length | width | height | flapHeight | glueArea |
-|-------|--------|-------|--------|------------|----------|
-| BECF-11D01 | 100 | 50 | 150 | 50 | 13 |
+| Model      | length | width | height | flapHeight | glueArea |
+| ---------- | ------ | ----- | ------ | ---------- | -------- |
+| BECF-11D01 | 100    | 50    | 150    | 50         | 13       |
+
+#### Carton Bags / Shopping Bags (BECF-12101, BECF-12109)
+
+```typescript
+interface CartonBagAttributes {
+  length: number; // A — bag length / front-back panel width (mm)
+  width: number; // B — bag width / side panel gusset (mm)
+  height: number; // C — bag body height (mm)
+  glueArea: number; // glue flap width (mm)
+}
+```
+
+Auto-calculated values (not user inputs):
+
+- `D` — top flap height = min(C - 2 - B/2, 40)
+- `DIP` — bottom glue tab height (15mm for 12101, 13mm for 12109)
+
+| Model               | length | width | height | glueArea |
+| ------------------- | ------ | ----- | ------ | -------- |
+| BECF-12101 (Type A) | 100    | 50    | 150    | 13       |
+| BECF-12109 (Type B) | 100    | 50    | 150    | 13       |
 
 ### Default Attribute Constants
 
@@ -191,7 +497,9 @@ import {
   BECF_1030A_DEFAULT_ATTRIBUTES,
   BECF_1040A_DEFAULT_ATTRIBUTES,
   BECF_11D01_DEFAULT_ATTRIBUTES,
-} from "ultimate-packaging";
+  BECF_12101_DEFAULT_ATTRIBUTES,
+  BECF_12109_DEFAULT_ATTRIBUTES,
+} from "@lucablockltd/ultimate-packaging";
 ```
 
 ---
@@ -202,21 +510,21 @@ import {
 
 ```typescript
 interface AutoLayoutConfig {
-  papers: AutoLayoutPaper[];        // paper sizes to try
-  model: AutoLayoutModel;           // { modelId, attributes }
-  quantity: number;                  // total pieces needed
-  layoutDistance: number;            // mm between piece cut-lines
-  spacing: number;                  // mm margin on paper sides
-  griper: number;                   // mm machine gripper zone
-  colorbarHeight: number;           // mm colorbar strip
-  isShowColorbar: boolean;          // show colorbar on layout
+  papers: AutoLayoutPaper[]; // paper sizes to try
+  model: AutoLayoutModel; // { modelId, attributes }
+  quantity: number; // total pieces needed
+  layoutDistance?: number; // mm between piece cut-lines (default: 3)
+  spacing?: number; // mm margin on paper sides (default: 5)
+  griper?: number; // mm machine gripper zone (default: 10)
+  colorbarHeight?: number; // mm colorbar strip (default: 5)
+  isShowColorbar?: boolean; // show colorbar on layout (default: true)
 }
 
 interface AutoLayoutPaper {
   paperId: string;
   paperName: string;
-  paperWidth: number;   // mm
-  paperHeight: number;  // mm
+  paperWidth: number; // mm
+  paperHeight: number; // mm
 }
 ```
 
@@ -224,7 +532,7 @@ interface AutoLayoutPaper {
 
 ```typescript
 interface AutoLayoutResult {
-  papers: AutoLayoutPaperResult[];  // results per paper size
+  papers: AutoLayoutPaperResult[]; // results per paper size
   quantity: number;
   totalProduced: number;
   totalSheets: number;
@@ -237,20 +545,20 @@ interface AutoLayoutPaperResult {
   paperName: string;
   paperWidth: number;
   paperHeight: number;
-  producedPerSheet: number;         // pieces per sheet
+  producedPerSheet: number; // pieces per sheet
   totalSheets: number;
   totalProduced: number;
-  excessCount: number;              // overproduction
-  wastePercent: number;             // paper waste %
-  independentSheets: number;        // sheets if using only this paper
-  independentTotalArea: number;     // total paper area (mm²)
+  excessCount: number; // overproduction
+  wastePercent: number; // paper waste %
+  independentSheets: number; // sheets if using only this paper
+  independentTotalArea: number; // total paper area (mm²)
   placements: AutoLayoutPlacement[];
-  gripperSide: GripperSide;         // "top" | "bottom" | "left" | "right"
+  gripperSide: GripperSide; // "top" | "bottom" | "left" | "right"
 }
 
 interface AutoLayoutPlacement {
-  x: number;        // mm from paper left
-  y: number;        // mm from paper top
+  x: number; // mm from paper left
+  y: number; // mm from paper top
   rotation: number; // 0 | 90 | 180 | 270
 }
 ```
@@ -260,8 +568,8 @@ interface AutoLayoutPlacement {
 ```typescript
 interface AutoLayoutPackedResult extends AutoLayoutPaperResult {
   quantity: number;
-  dielineFile: File;   // dieline pattern image
-  layoutFile: File;    // layout arrangement image
+  dielineFile: File; // dieline pattern image
+  layoutFile: File; // layout arrangement image
 }
 ```
 
@@ -275,15 +583,17 @@ type ModelMode = "DIE_LINE" | "3D" | "AUTO_LAYOUT";
 
 ## 5. Theme Configuration
 
+`configurePackaging()` must be called **ONCE before rendering** any packaging components. All fields are optional — only override what you need.
+
 ```tsx
-import { configurePackaging } from "ultimate-packaging";
+import { configurePackaging } from "@lucablockltd/ultimate-packaging";
 
-// Call ONCE at app startup, BEFORE rendering any components
 configurePackaging({
+  fontDimensionSize: 4.2, // dimension label font size (default: 4.2)
   modelTheme: {
     colorBackground: "#FAFAFA",
-    colorDieLine: "#FF0000",     // cut lines
-    colorFoldLine: "#00FF00",    // crease lines
+    colorDieLine: "#FF0000", // cut lines
+    colorFoldLine: "#00FF00", // crease lines
   },
   autoLayoutTheme: {
     colorBackground: "#F5F5F5",
@@ -299,6 +609,95 @@ configurePackaging({
 });
 ```
 
+### Where to call `configurePackaging()` per framework
+
+#### Vite / CRA (Client-side SPA)
+
+Call in `main.tsx` before `createRoot().render()`:
+
+```tsx
+// main.tsx
+import { configurePackaging } from "@lucablockltd/ultimate-packaging";
+
+configurePackaging({ modelTheme: { colorDieLine: "#FF0000" } });
+
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+#### Next.js (App Router)
+
+Create a client-side provider component and use it in the root layout:
+
+```tsx
+// components/PackagingProvider.tsx
+"use client";
+
+import { configurePackaging } from "@lucablockltd/ultimate-packaging";
+
+// Runs once on module load (client-side only)
+configurePackaging({
+  modelTheme: { colorDieLine: "#FF0000" },
+  autoLayoutTheme: { colorDistanceLine: "#0088FF" },
+});
+
+export default function PackagingProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <>{children}</>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import PackagingProvider from "@/components/PackagingProvider";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <PackagingProvider>{children}</PackagingProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+> **Why a `"use client"` provider?** — `configurePackaging()` sets a global variable. In Next.js App Router, server components run on the server where this global has no effect. Using `"use client"` ensures the config runs in the browser before any packaging components render.
+
+#### Next.js (Pages Router)
+
+Call in `_app.tsx`:
+
+```tsx
+// pages/_app.tsx
+import { configurePackaging } from "@lucablockltd/ultimate-packaging";
+import type { AppProps } from "next/app";
+
+configurePackaging({
+  modelTheme: { colorDieLine: "#FF0000" },
+  autoLayoutTheme: { colorDistanceLine: "#0088FF" },
+});
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+#### Remix
+
+Call in `root.tsx` or a client-only module:
+
+```tsx
+// app/root.tsx
+import { configurePackaging } from "@lucablockltd/ultimate-packaging";
+
+configurePackaging({
+  modelTheme: { colorDieLine: "#FF0000" },
+});
+```
+
 ---
 
 ## 6. Complete Imports Cheat Sheet
@@ -306,15 +705,17 @@ configurePackaging({
 ```tsx
 // Components
 import {
-  DIE_LINE_LAYOUT,           // Recommended: auto-switches by modelId
-  AUTO_LAYOUT,               // Auto-layout packing on paper
-  MODEL_BECF_1010A,          // Direct model components (if needed)
+  DIE_LINE_LAYOUT, // Recommended: auto-switches by modelId
+  AUTO_LAYOUT, // Auto-layout packing on paper
+  MODEL_BECF_1010A, // Direct model components (if needed)
   MODEL_BECF_1030A,
   MODEL_BECF_1040A,
   MODEL_BECF_11D01,
-  Colorbar,                  // Sub-components for custom rendering
+  MODEL_BECF_12101,
+  MODEL_BECF_12109,
+  Colorbar, // Sub-components for custom rendering
   Gripper,
-} from "ultimate-packaging";
+} from "@lucablockltd/ultimate-packaging";
 
 // Types
 import type {
@@ -329,8 +730,11 @@ import type {
   AutoLayoutPlacement,
   AutoLayoutPaper,
   AutoLayoutModel,
+  AutoLayoutAction,
   TuckEndBoxAttributes,
   StandardBoxAttributes,
+  CartonBagAttributes,
+  CartonBag12109Attributes,
   ModelMode,
   PackagingModel,
   GripperSide,
@@ -338,24 +742,26 @@ import type {
   ModelThemeConfig,
   AutoLayoutThemeConfig,
   UltimatePackagingConfig,
-} from "ultimate-packaging";
+} from "@lucablockltd/ultimate-packaging";
 
 // Data & Constants
 import {
-  modelList,                        // PackagingModel[] — all models with defaults
+  modelList, // PackagingModel[] — all models with defaults
   BECF_1010A_DEFAULT_ATTRIBUTES,
   BECF_1030A_DEFAULT_ATTRIBUTES,
   BECF_1040A_DEFAULT_ATTRIBUTES,
   BECF_11D01_DEFAULT_ATTRIBUTES,
+  BECF_12101_DEFAULT_ATTRIBUTES,
+  BECF_12109_DEFAULT_ATTRIBUTES,
   MODEL_THEME_CONFIG,
   AUTO_LAYOUT_THEME_CONFIG,
-} from "ultimate-packaging";
+} from "@lucablockltd/ultimate-packaging";
 
 // Functions
 import {
-  configurePackaging,               // Set global theme
-  calculateAutoLayout,              // Compute layout without UI
-} from "ultimate-packaging";
+  configurePackaging, // Set global theme
+  calculateAutoLayout, // Compute layout without UI
+} from "@lucablockltd/ultimate-packaging";
 ```
 
 ---
@@ -365,8 +771,8 @@ import {
 ### Pattern A: Display a Dieline with Controls
 
 ```tsx
-import { DIE_LINE_LAYOUT, modelList } from "ultimate-packaging";
-import type { DieLineLayoutRef } from "ultimate-packaging";
+import { DIE_LINE_LAYOUT, modelList } from "@lucablockltd/ultimate-packaging";
+import type { DieLineLayoutRef } from "@lucablockltd/ultimate-packaging";
 
 function DielineEditor() {
   const ref = useRef<DieLineLayoutRef>(null);
@@ -375,13 +781,20 @@ function DielineEditor() {
 
   const handleModelChange = (id: string) => {
     setModelId(id);
-    setAttrs(modelList.find(m => m.id === id)!.attributes);
+    setAttrs(modelList.find((m) => m.id === id)!.attributes);
   };
 
   return (
     <>
-      <select value={modelId} onChange={e => handleModelChange(e.target.value)}>
-        {modelList.map(m => <option key={m.id} value={m.id}>{m.nameEN}</option>)}
+      <select
+        value={modelId}
+        onChange={(e) => handleModelChange(e.target.value)}
+      >
+        {modelList.map((m) => (
+          <option key={m.id} value={m.id}>
+            {m.nameEN}
+          </option>
+        ))}
       </select>
       <DIE_LINE_LAYOUT ref={ref} modelId={modelId} attributes={attrs} />
     </>
@@ -392,16 +805,37 @@ function DielineEditor() {
 ### Pattern B: Auto-Layout with Export
 
 ```tsx
-import { AUTO_LAYOUT } from "ultimate-packaging";
-import type { AutoLayoutRef, AutoLayoutConfig, AutoLayoutResult } from "ultimate-packaging";
+import { AUTO_LAYOUT } from "@lucablockltd/ultimate-packaging";
+import type {
+  AutoLayoutRef,
+  AutoLayoutConfig,
+  AutoLayoutResult,
+} from "@lucablockltd/ultimate-packaging";
 
 function LayoutPlanner() {
   const ref = useRef<AutoLayoutRef>(null);
   const [result, setResult] = useState<AutoLayoutResult | null>(null);
 
   const config: AutoLayoutConfig = {
-    papers: [{ paperId: "1", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 }],
-    model: { modelId: "BECF-1010A", attributes: { length: 60, width: 25, height: 100, glueArea: 15, dustFlap: 15, tuckFlap: 15 } },
+    papers: [
+      {
+        paperId: "1",
+        paperName: '20x28"',
+        paperWidth: 508,
+        paperHeight: 711.2,
+      },
+    ],
+    model: {
+      modelId: "BECF-1010A",
+      attributes: {
+        length: 60,
+        width: 25,
+        height: 100,
+        glueArea: 15,
+        dustFlap: 15,
+        tuckFlap: 15,
+      },
+    },
     quantity: 500,
     layoutDistance: 3,
     spacing: 5,
@@ -420,7 +854,12 @@ function LayoutPlanner() {
   return (
     <>
       <AUTO_LAYOUT ref={ref} config={config} onResult={setResult} />
-      {result && <p>Best: {result.recommendedPaperId} — {result.papers[0].producedPerSheet} pcs/sheet</p>}
+      {result && (
+        <p>
+          Best: {result.recommendedPaperId} —{" "}
+          {result.papers[0].producedPerSheet} pcs/sheet
+        </p>
+      )}
       <button onClick={handleExport}>Export</button>
     </>
   );
@@ -430,14 +869,24 @@ function LayoutPlanner() {
 ### Pattern C: Headless Calculation (No React)
 
 ```tsx
-import { calculateAutoLayout } from "ultimate-packaging";
+import { calculateAutoLayout } from "@lucablockltd/ultimate-packaging";
 
 const result = calculateAutoLayout({
   papers: [
-    { paperId: "A", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 },
-    { paperId: "B", paperName: "25x36\"", paperWidth: 635, paperHeight: 914.4 },
+    { paperId: "A", paperName: '20x28"', paperWidth: 508, paperHeight: 711.2 },
+    { paperId: "B", paperName: '25x36"', paperWidth: 635, paperHeight: 914.4 },
   ],
-  model: { modelId: "BECF-1030A", attributes: { length: 105, width: 50, height: 155, glueArea: 15, dustFlap: 25, tuckFlap: 14 } },
+  model: {
+    modelId: "BECF-1030A",
+    attributes: {
+      length: 105,
+      width: 50,
+      height: 155,
+      glueArea: 15,
+      dustFlap: 25,
+      tuckFlap: 14,
+    },
+  },
   quantity: 1000,
   layoutDistance: 3,
   spacing: 5,
@@ -447,8 +896,10 @@ const result = calculateAutoLayout({
 });
 
 console.log(result.recommendedPaperId); // "B"
-result.papers.forEach(p => {
-  console.log(`${p.paperName}: ${p.producedPerSheet} pcs/sheet, ${p.wastePercent}% waste`);
+result.papers.forEach((p) => {
+  console.log(
+    `${p.paperName}: ${p.producedPerSheet} pcs/sheet, ${p.wastePercent}% waste`,
+  );
 });
 ```