Documentation Index
Fetch the complete documentation index at: https://mintlify.com/PloutusLab/krafta-web/llms.txt
Use this file to discover all available pages before exploring further.
Template Studio is the advanced surface configuration layer embedded inside the catalog edit flow at /admin/catalog/edit/[id]. It provides a full-screen SVG editor (PrintAreaEditor) where admins upload vector mockup files per product view (Front, Back, Sleeve, etc.), detect structural print zones automatically from reserved SVG layer IDs, configure customer-selectable color variables, and save the result as a svgContent JSON blob on the Product record.
Template Studio does not manage SurfaceTemplateVersion records through the UI — those are database-level entities for advanced versioning. Day-to-day product configuration is handled entirely through the PrintAreaEditor embedded in the catalog edit flow.
How it works
Template Studio opens as a fixed full-screen overlay with three panels:
- Left sidebar (Asset Manager) — list of views for the product. Each view has a name, a status dot (green = SVG uploaded, grey = missing), and controls to reorder, rename, or delete views. An Add New View button appends a blank view.
- Center canvas — SVG preview area with a dotted background. Detected
#krafta-print-area and #krafta-safe-zone layers are highlighted with colored overlay rectangles. A zoom control and an Upload / Replace SVG button sit in the top-right corner.
- Right sidebar (Product Architecture) — shows layer detection status (
DETECTED / MISSING) for Base Mockup, Print Area, and Safe Zone, plus the list of detected Dynamic Variables with color pickers. A Save button commits the configuration.
Work-in-progress is autosaved to localStorage under the key krafta_admin_studio_draft_<productId> with a 1-second debounce, so accidental navigation does not lose unsaved layer data.
SVG layer naming conventions
SVG files uploaded to Template Studio must use the following reserved element IDs so the editor can detect and overlay the structural print zones:
| SVG Element ID | Purpose |
|---|
#krafta-base (or #_x23_krafta-base) | Base layer of the product mockup. Used as the foundational visual beneath all design compositing. |
#krafta-print-area (or #_x23_krafta-print-area) | The printable zone where customer designs are placed. The editor draws a dashed blue overlay on this layer. |
#krafta-safe-zone (or #_x23_krafta-safe-zone) | Inner safe boundary. Designs fully within this zone avoid edge trimming. The editor draws a dashed green overlay on this layer. |
#krafta-var-<name> (or #_x23_krafta-var-<name>) | Colorizable product variable layer (e.g. #krafta-var-sleeve). Each matching element becomes a color variable in the right sidebar. |
#color_base (or #color_x5F_base) | Alternative naming for the base color variable layer. |
querySelector with wildcard matching ([id*='krafta-print-area'], [id*='krafta-safe-zone'], etc.). If both a print area and a safe zone are present, the print area takes precedence as the primary overlay. If no #krafta-print-area layer is found, the safe zone is used as a fallback.
Dynamic color variables
Any SVG layer whose ID matches krafta-var-* or krafta-base (in any of the naming variants above) is detected as a Dynamic Variable. For each variable the right sidebar shows:
- A label derived from the layer ID with underscores replaced by spaces.
- One or more color swatches (color pickers). The first swatch sets the default fill. Admins can add additional palette options with Add Color — these become the selectable colors shown to customers in the design editor.
Variable color changes are previewed live on the center canvas via injected <style> rules.
Saving a product template
Clicking Continuar a Mockups Realistas (Save) in the right sidebar calls the onSave callback, which passes a manifest object structured as follows:
{
"svgContent": "<svg>...</svg>",
"printArea": { "x": 22.5, "y": 18.0, "width": 55.0, "height": 48.0 },
"safeZone": { "x": 25.0, "y": 20.0, "width": 50.0, "height": 44.0 },
"views": [
{
"id": "front",
"label": "Front",
"svgContent": "<svg>...</svg>",
"printArea": { "x": 22.5, "y": 18.0, "width": 55.0, "height": 48.0 },
"safeZone": { "x": 25.0, "y": 20.0, "width": 50.0, "height": 44.0 },
"variables": [
{
"id": "krafta-var-sleeve",
"label": "sleeve",
"color": "#ffffff",
"colors": [
{ "hex": "#ffffff" },
{ "hex": "#000000" },
{ "hex": "#1a1a2e" }
]
}
]
}
]
}
printArea and safeZone are percentages (0–100) relative to the SVG viewBox dimensions, computed at save time from the detected layer’s bounding box. These percentage values are stored in the PrintTemplate.printAreaX, printAreaY, printAreaWidth, and printAreaHeight fields on the variant record.
The full views array plus SVG content is serialized and stored in Product.svgContent so the customer-facing design editor can reconstruct the exact canvas configuration.
SurfaceTemplateVersion model
The SurfaceTemplateVersion table provides a versioned, immutable-once-published template layer for advanced production use cases. It stores a manifestJson field of type Json with the complete template specification. This table is currently managed directly via Prisma Studio, not through the admin UI.
| Field | Type | Description |
|---|
id | String (UUID) | Primary key |
templateKey | String | Identifier such as hoodie-crop-ls12000-printify-217-black-back |
title | String | Admin-facing display name |
subtitle | String? | Optional subtitle |
version | Int | Monotonically increasing version number, starting at 1 |
status | String | DRAFT, PUBLISHED, or ARCHIVED |
manifestJson | Json | Full template configuration object (structure defined by your production pipeline) |
createdAt | DateTime | Creation timestamp |
updatedAt | DateTime | Last modification timestamp |
Version lifecycle
DRAFT → PUBLISHED → ARCHIVED
- DRAFT — editable; not yet referenced by the design editor in production sessions.
- PUBLISHED — immutable; active version served to new design sessions.
- ARCHIVED — retired; still referenced by any historical orders but no new sessions are assigned to it.
MockupScene model
Each SurfaceTemplateVersion can have one or more MockupScene records that define how a customer’s design is composited onto the product photo.
| Field | Description |
|---|
mode | Rendering mode: flat, cylinder, or mesh (default flat) |
baseImageUrl | URL of the product base photograph |
productMaskUrl | Optional mask image isolating the printable region for compositing |
shadowUrl | Optional shadow layer applied over the design for realism |
highlightUrl | Optional highlight/sheen layer for fabric texture |
displacementMapUrl | Optional displacement map for mesh-warp mode |
configJson | Additional renderer-specific parameters as a JSON object |
PrintAreaEditor component
The PrintAreaEditor component is mounted in the catalog edit page (/admin/catalog/edit/[id]). It accepts:
| Prop | Type | Description |
|---|
manifest | object | Existing product SVG data loaded from Product.svgContent |
productId | string | Used as the localStorage draft key (krafta_admin_studio_draft_<productId>) |
onSave | function | Callback receiving the resolved manifest object on save |
window.history.back() on the back button to return to the catalog edit page without losing unsaved work (autosave to localStorage handles recovery).
