@templatical/template-tools 0.46.0 → 0.48.0

package/dist/src-SZZkttBC.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"src-SZZkttBC.js","names":[],"sources":["../src/operations.ts"],"sourcesContent":["// A pure reducer over the template operation vocabulary.\n//\n// `applyOperation(content, payload) -> { ok, content, error }`. The input is\n// never mutated: every operation works on a `safeClone` and returns a new\n// document, so a rejected operation leaves the caller's copy provably untouched.\n//\n// Two deliberate differences from the editor's own mutators in\n// `@templatical/core` (`src/editor.ts`), which this mirrors:\n//\n//  1. **Failure is explicit.** Core silently `return`s on an invalid operation,\n//     which is right for a UI — a drag that can't drop simply doesn't. An agent\n//     gets no such feedback, so a silent no-op would read as success and the\n//     next instruction would build on a state that never happened. Every\n//     rejection here carries a reason.\n//  2. **No collaboration locks.** `lockedBlocks` is a Cloud concern; this runs\n//     against a local working file with a single writer.\n//\n// Core is FSL and cannot be imported here, so the shared invariants — above all\n// the section-into-column refusal (issue #292) — are reimplemented. That is a\n// real drift risk: a guard added to core will not appear here. `tests/\n// operations.test.ts` states each invariant against both descriptions so the\n// pair has to be reconciled deliberately.\n//\n// Note the payload keys are camelCase (`blockId`, `targetSectionId`), matching\n// `@templatical/types` and core. Cloud's MCP tools emit snake_case in their own\n// `data` payloads, so this reducer is NOT wire-compatible with Cloud broadcasts\n// and is not meant to be.\n\nimport { safeClone } from \"@templatical/types\";\nimport type {\n  Block,\n  ColumnLayout,\n  TemplateOperationPayload,\n  SectionBlock,\n  TemplateContent,\n  TemplateSettings,\n} from \"@templatical/types\";\n\n/** Columns a layout declares. Mirrors the helper in core's editor. */\nexport function getColumnCount(layout: ColumnLayout): number {\n  if (layout === \"1\") return 1;\n  if (layout === \"3\") return 3;\n  return 2;\n}\n\nfunction findBlockById(blocks: Block[], id: string): Block | null {\n  for (const block of blocks) {\n    if (block.id === id) return block;\n    if (block.type === \"section\") {\n      for (const column of block.children) {\n        const found = findBlockById(column, id);\n        if (found) return found;\n      }\n    }\n  }\n  return null;\n}\n\ninterface ParentRef {\n  blocks: Block[];\n  sectionId?: string;\n  columnIndex?: number;\n}\n\nfunction findBlockParent(\n  blocks: Block[],\n  id: string,\n  parent: ParentRef = { blocks },\n): ParentRef | null {\n  for (const block of blocks) {\n    if (block.id === id) return parent;\n    if (block.type === \"section\") {\n      for (let colIdx = 0; colIdx < block.children.length; colIdx++) {\n        const result = findBlockParent(block.children[colIdx], id, {\n          blocks: block.children[colIdx],\n          sectionId: block.id,\n          columnIndex: colIdx,\n        });\n        if (result) return result;\n      }\n    }\n  }\n  return null;\n}\n\nexport interface OperationResult {\n  ok: boolean;\n  /** The new document on success; the unchanged input on failure. */\n  content: TemplateContent;\n  error?: string;\n}\n\nfunction reject(content: TemplateContent, error: string): OperationResult {\n  return { ok: false, content, error };\n}\n\n/**\n * Resolve the array an operation targets, enforcing the column rules.\n * Returns a string on rejection so callers can surface the reason.\n */\nfunction resolveTarget(\n  content: TemplateContent,\n  targetSectionId: string | undefined,\n  columnIndex: number,\n): Block[] | string {\n  if (!targetSectionId) return content.blocks;\n\n  const section = findBlockById(content.blocks, targetSectionId);\n  if (!section) return `No block with id \"${targetSectionId}\".`;\n  if (section.type !== \"section\") {\n    return `Block \"${targetSectionId}\" is a ${section.type}, not a section — it has no columns.`;\n  }\n  const count = getColumnCount((section as SectionBlock).columns);\n  if (columnIndex < 0 || columnIndex >= count) {\n    return `Column ${columnIndex} is out of range for a \"${(section as SectionBlock).columns}\" section (${count} column(s)).`;\n  }\n  const children = section as SectionBlock;\n  children.children[columnIndex] = children.children[columnIndex] || [];\n  return children.children[columnIndex];\n}\n\nfunction insertAt(target: Block[], block: Block, index?: number): void {\n  if (index !== undefined && index < target.length) {\n    target.splice(index, 0, block);\n  } else {\n    target.push(block);\n  }\n}\n\ntype Data = Record<string, unknown>;\n\n/** Apply one operation, returning a new document. Never mutates the input. */\nexport function applyOperation(\n  content: TemplateContent,\n  payload: TemplateOperationPayload,\n): OperationResult {\n  const data = (payload.data ?? {}) as Data;\n\n  switch (payload.operation) {\n    case \"setContent\": {\n      const next = data.content as TemplateContent | undefined;\n      if (!next || typeof next !== \"object\" || !Array.isArray(next.blocks)) {\n        return reject(\n          content,\n          \"setContent needs `content` with a blocks array.\",\n        );\n      }\n      return { ok: true, content: safeClone(next) };\n    }\n\n    case \"updateSettings\": {\n      const updates = data.settings as Partial<TemplateSettings> | undefined;\n      if (!updates || typeof updates !== \"object\") {\n        return reject(content, \"updateSettings needs a `settings` object.\");\n      }\n      const draft = safeClone(content);\n      draft.settings = { ...draft.settings, ...updates };\n      return { ok: true, content: draft };\n    }\n\n    case \"addBlock\": {\n      const block = data.block as Block | undefined;\n      if (!block || typeof block !== \"object\" || typeof block.id !== \"string\") {\n        return reject(content, \"addBlock needs a `block` with an id.\");\n      }\n      const targetSectionId = data.targetSectionId as string | undefined;\n\n      // Sections cannot nest inside a column — MJML forbids `mj-section` inside\n      // `mj-column`, so the renderer drops them on export (issue #292). Reject\n      // up front rather than lose the content silently at render time.\n      if (targetSectionId && block.type === \"section\") {\n        return reject(\n          content,\n          \"A section cannot be nested inside a section column — MJML would drop it on export. Add it at the top level instead.\",\n        );\n      }\n\n      const draft = safeClone(content);\n      if (findBlockById(draft.blocks, block.id)) {\n        return reject(content, `A block with id \"${block.id}\" already exists.`);\n      }\n      const target = resolveTarget(\n        draft,\n        targetSectionId,\n        (data.columnIndex as number | undefined) ?? 0,\n      );\n      if (typeof target === \"string\") return reject(content, target);\n\n      insertAt(target, safeClone(block), data.index as number | undefined);\n      return { ok: true, content: draft };\n    }\n\n    case \"updateBlock\": {\n      const blockId = data.blockId as string | undefined;\n      const updates = data.updates as Partial<Block> | undefined;\n      if (!blockId) return reject(content, \"updateBlock needs a `blockId`.\");\n      if (!updates || typeof updates !== \"object\") {\n        return reject(content, \"updateBlock needs an `updates` object.\");\n      }\n      const draft = safeClone(content);\n      const block = findBlockById(draft.blocks, blockId);\n      if (!block) return reject(content, `No block with id \"${blockId}\".`);\n      if (\"type\" in updates && updates.type !== block.type) {\n        // Changing type in place would leave the block carrying the previous\n        // type's fields, which no longer validate against its new subschema.\n        return reject(\n          content,\n          `Cannot change a block's type (${block.type} → ${String(updates.type)}). Delete it and add the new block instead.`,\n        );\n      }\n      Object.assign(block, updates);\n      return { ok: true, content: draft };\n    }\n\n    case \"updateBlockStyle\": {\n      const blockId = data.blockId as string | undefined;\n      const styles = data.styles as Record<string, unknown> | undefined;\n      if (!blockId) {\n        return reject(content, \"updateBlockStyle needs a `blockId`.\");\n      }\n      if (!styles || typeof styles !== \"object\") {\n        return reject(content, \"updateBlockStyle needs a `styles` object.\");\n      }\n      const draft = safeClone(content);\n      const block = findBlockById(draft.blocks, blockId);\n      if (!block) return reject(content, `No block with id \"${blockId}\".`);\n      // Merge rather than replace, so a caller can set one property without\n      // restating padding and every other style the block already carries.\n      block.styles = {\n        ...block.styles,\n        ...styles,\n      } as Block[\"styles\"];\n      return { ok: true, content: draft };\n    }\n\n    case \"deleteBlock\": {\n      const blockId = data.blockId as string | undefined;\n      if (!blockId) return reject(content, \"deleteBlock needs a `blockId`.\");\n      const draft = safeClone(content);\n      const parent = findBlockParent(draft.blocks, blockId);\n      if (!parent) return reject(content, `No block with id \"${blockId}\".`);\n      const index = parent.blocks.findIndex((b) => b.id === blockId);\n      parent.blocks.splice(index, 1);\n      return { ok: true, content: draft };\n    }\n\n    case \"moveBlock\": {\n      const blockId = data.blockId as string | undefined;\n      const index = data.index as number | undefined;\n      if (!blockId) return reject(content, \"moveBlock needs a `blockId`.\");\n      if (typeof index !== \"number\" || index < 0) {\n        return reject(content, \"moveBlock needs a non-negative `index`.\");\n      }\n      const targetSectionId = data.targetSectionId as string | undefined;\n\n      const draft = safeClone(content);\n      const parent = findBlockParent(draft.blocks, blockId);\n      if (!parent) return reject(content, `No block with id \"${blockId}\".`);\n      const oldIndex = parent.blocks.findIndex((b) => b.id === blockId);\n\n      if (targetSectionId && parent.blocks[oldIndex].type === \"section\") {\n        return reject(\n          content,\n          \"A section cannot be moved into a section column — MJML would drop it on export.\",\n        );\n      }\n      if (targetSectionId === blockId) {\n        return reject(content, \"A block cannot be moved into itself.\");\n      }\n\n      // Resolve the target BEFORE splicing the source: an invalid target would\n      // otherwise leave the block removed and unrecoverable.\n      const target = resolveTarget(\n        draft,\n        targetSectionId,\n        (data.columnIndex as number | undefined) ?? 0,\n      );\n      if (typeof target === \"string\") return reject(content, target);\n\n      const [block] = parent.blocks.splice(oldIndex, 1);\n      target.splice(index, 0, block);\n      return { ok: true, content: draft };\n    }\n\n    default: {\n      return reject(\n        content,\n        `Unknown operation \"${String(payload.operation)}\".`,\n      );\n    }\n  }\n}\n"],"mappings":"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"}

package/live/index.html

@@ -1304,6 +1304,58 @@
       };
 
       // ---- Boot ----
+      // ---- Custom-block mode ----
+      // The bridge serves the definition without its preview recipe; onFetch
+      // asks the bridge, which holds the recipe and the secrets. The page sends
+      // fieldValues only — never a URL or headers.
+      let customBlock = null; // { definition, dataSource: { label } | null }
+
+      async function loadCustomBlock() {
+        try {
+          const res = await fetch("/custom-block");
+          if (res.status === 200) {
+            customBlock = await res.json();
+          } else {
+            customBlock = null;
+            if (res.status === 422) {
+              toast((await res.json().catch(() => ({}))).error ?? "Custom block is invalid");
+            }
+          }
+        } catch {
+          customBlock = null;
+        }
+      }
+
+      function customBlocksConfig() {
+        if (!customBlock) return undefined;
+        const definition = { ...customBlock.definition };
+        if (customBlock.dataSource) {
+          definition.dataSource = {
+            label: customBlock.dataSource.label,
+            onFetch: async ({ fieldValues }) => {
+              const res = await fetch("/data-source/fetch", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ fieldValues }),
+              });
+              const body = await res.json().catch(() => ({}));
+              // Throwing (not returning null, which reads as "cancelled") puts
+              // the toolbar in its fetch-error state, which stays visible.
+              if (!res.ok) {
+                const message = body.error ?? "Fetch failed";
+                toast(message);
+                throw new Error(message);
+              }
+              if (body.unmapped?.length) {
+                toast("Not in the response: " + body.unmapped.join(", "));
+              }
+              return body.values;
+            },
+          };
+        }
+        return [definition];
+      }
+
       async function mountEditor(content) {
         applyingRemote = true;
         try {
@@ -1316,6 +1368,7 @@
             locale: readLocale(),
             content, // undefined → editor starts from its default empty template
             uiTheme: readTheme(),
+            customBlocks: customBlocksConfig(),
             onChange: () => {
               if (!applyingRemote) scheduleContentPost();
             },
@@ -1328,6 +1381,7 @@
       }
 
       async function boot() {
+        await loadCustomBlock();
         let content;
         try {
           const res = await fetch("/template");
@@ -1348,6 +1402,16 @@
             /* malformed frame; ignore */
           }
         });
+        es.addEventListener("custom-block", async (e) => {
+          try {
+            const { block, template } = JSON.parse(e.data);
+            customBlock = block;
+            await mountEditor(template);
+            toast("Updated from agent");
+          } catch {
+            /* malformed frame; ignore */
+          }
+        });
         es.onopen = () => setStatus("live", "Live");
         es.onerror = () => setStatus("reconnecting", "Reconnecting…");
       }

package/package.json

@@ -1,23 +1,25 @@
 {
   "name": "@templatical/template-tools",
   "description": "CLI and library for Templatical email templates — validate, render, edit, import, and live-preview",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "bin": {
     "templatical": "./dist/bin.js"
   },
   "bugs": "https://github.com/templatical/sdk/issues",
   "dependencies": {
-    "@templatical/quality": "0.46.0",
-    "@templatical/renderer": "0.46.0",
-    "@templatical/types": "0.46.0",
-    "ajv": "^8.20.0"
+    "@templatical/quality": "0.48.0",
+    "@templatical/renderer": "0.48.0",
+    "@templatical/types": "0.48.0",
+    "ajv": "^8.20.0",
+    "htmlparser2": "^12.0.0",
+    "liquidjs": "^10.30.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.9",
     "mjml": "^5.4.1",
     "ts-json-schema-generator": "^2.9.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.4"
   },
   "exports": {
     ".": {
@@ -28,13 +30,15 @@
       "types": "./dist/live/index.d.ts",
       "import": "./dist/live/index.js"
     },
-    "./schema.json": "./schema.json"
+    "./schema.json": "./schema.json",
+    "./custom-block-schema.json": "./custom-block-schema.json"
   },
   "files": [
     "README.md",
     "dist",
     "live",
-    "schema.json"
+    "schema.json",
+    "custom-block-schema.json"
   ],
   "homepage": "https://templatical.com",
   "keywords": [
@@ -48,14 +52,14 @@
   "license": "MIT",
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@templatical/import-beefree": "0.46.0",
-    "@templatical/import-chamaileon": "0.46.0",
-    "@templatical/import-easy-email-pro": "0.46.0",
-    "@templatical/import-html": "0.46.0",
-    "@templatical/import-mjml": "0.46.0",
-    "@templatical/import-stripo": "0.46.0",
-    "@templatical/import-topol": "0.46.0",
-    "@templatical/import-unlayer": "0.46.0",
+    "@templatical/import-beefree": "0.48.0",
+    "@templatical/import-chamaileon": "0.48.0",
+    "@templatical/import-easy-email-pro": "0.48.0",
+    "@templatical/import-html": "0.48.0",
+    "@templatical/import-mjml": "0.48.0",
+    "@templatical/import-stripo": "0.48.0",
+    "@templatical/import-topol": "0.48.0",
+    "@templatical/import-unlayer": "0.48.0",
     "mjml": "^5.4.1"
   },
   "peerDependenciesMeta": {

package/schema.json

@@ -140,6 +140,14 @@
           "$ref": "#/definitions/BorderValue",
           "description": "Border around the section box, per side. Omitted = no border; a side with width 0 is not drawn."
         },
+        "backgroundImage": {
+          "$ref": "#/definitions/BackgroundImage",
+          "description": "Image behind the section's columns, rendered as `background-url` (plus size, position and repeat) on the `mj-section`. `styles.backgroundColor` is its fallback."
+        },
+        "hero": {
+          "$ref": "#/definitions/SectionHero",
+          "description": "Draws a one-column section with a background image as an `mj-hero`: the image fills the box and the content sits on top. Ignored (the section renders as a regular one, and the `structure` linter says why) with more than one column, without an image, or with `height: \"image\"` and no image size."
+        },
         "wrapper": {
           "$ref": "#/definitions/SectionWrapper",
           "description": "Optional outer frame (rendered as an `mj-wrapper` around the section)."
@@ -310,6 +318,113 @@
         "dotted"
       ]
     },
+    "BackgroundImage": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string"
+        },
+        "size": {
+          "$ref": "#/definitions/BackgroundSize"
+        },
+        "position": {
+          "type": "object",
+          "properties": {
+            "x": {
+              "$ref": "#/definitions/BackgroundPositionX"
+            },
+            "y": {
+              "$ref": "#/definitions/BackgroundPositionY"
+            }
+          },
+          "required": [
+            "x",
+            "y"
+          ],
+          "additionalProperties": false
+        },
+        "repeat": {
+          "type": "boolean",
+          "description": "`false` paints the image once; `true` tiles it."
+        },
+        "naturalWidth": {
+          "type": "number",
+          "description": "The image file's own width in px, when known: given by the media library, measured by the editor when the author sets the URL, or read by an importer (from MJML, the hero's `background-width`, which may be the box's size rather than the file's). Only the ratio with `naturalHeight` is used: a section hero with `height: \"image\"` keeps its box at that shape. Both or neither; one without the other reads as unknown."
+        },
+        "naturalHeight": {
+          "type": "number",
+          "description": "The image file's own height in px, when known; it pairs with `naturalWidth`, and only their ratio is used. Both or neither."
+        }
+      },
+      "required": [
+        "url",
+        "size",
+        "position",
+        "repeat"
+      ],
+      "additionalProperties": false,
+      "description": "An image painted behind a section or a wrapper band. The element's own `backgroundColor` is its fallback: it shows while the image loads, with images off, and in clients without background-image support."
+    },
+    "BackgroundSize": {
+      "type": "string",
+      "enum": [
+        "cover",
+        "contain",
+        "auto"
+      ],
+      "description": "`background-size` keywords. In Outlook on Windows (VML), `cover` and `contain` draw a single frame when `repeat` is off and tile when it is on; `auto` always tiles from the top center, whatever `position` and `repeat` say."
+    },
+    "BackgroundPositionX": {
+      "type": "string",
+      "enum": [
+        "left",
+        "center",
+        "right"
+      ]
+    },
+    "BackgroundPositionY": {
+      "type": "string",
+      "enum": [
+        "top",
+        "center",
+        "bottom"
+      ]
+    },
+    "SectionHero": {
+      "type": "object",
+      "properties": {
+        "height": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "image"
+            },
+            {
+              "type": "number"
+            }
+          ],
+          "description": "`\"image\"` makes the box as tall as the image drawn across its desktop width, and needs the image's size on `backgroundImage.naturalWidth` / `naturalHeight`; a phone keeps that height and crops the image's sides. A number is the box's fixed height in px, padding included."
+        },
+        "verticalAlign": {
+          "$ref": "#/definitions/HeroVerticalAlign"
+        }
+      },
+      "required": [
+        "height",
+        "verticalAlign"
+      ],
+      "additionalProperties": false,
+      "description": "Draws a one-column section as an MJML `mj-hero`: its background image fills the box (always `cover`, never tiled) and the content sits on top of it. A hero applies only to a one-column section with a background image; otherwise the section renders as a regular one."
+    },
+    "HeroVerticalAlign": {
+      "type": "string",
+      "enum": [
+        "top",
+        "middle",
+        "bottom"
+      ],
+      "description": "Where a hero's content sits in its box."
+    },
     "SectionWrapper": {
       "type": "object",
       "properties": {
@@ -322,6 +437,10 @@
         "borderRadius": {
           "$ref": "#/definitions/BorderRadiusValue",
           "description": "Corner radius in px for the outer frame — one number, or a radius per corner. Omitted/0 = square corners."
+        },
+        "backgroundImage": {
+          "$ref": "#/definitions/BackgroundImage",
+          "description": "Image behind the band; `backgroundColor` is its fallback."
         }
       },
       "additionalProperties": false,
@@ -531,6 +650,13 @@
           "type": "number",
           "description": "Height in pixels. Absent means the height is derived from the width, so the image keeps its aspect ratio — setting both stretches it, since email clients don't support `object-fit`."
         },
+        "naturalWidth": {
+          "type": "number",
+          "description": "The image file's own size in px, when known: given by the media library, read by an importer, or measured in the editor during an edit. Both or neither; one without the other reads as unknown. It drives the editor's aspect-ratio lock and is never rendered. Cleared when `src` changes without a new size alongside it."
+        },
+        "naturalHeight": {
+          "type": "number"
+        },
         "align": {
           "type": "string",
           "enum": [
@@ -1567,6 +1693,10 @@
         "renderedHtml": {
           "type": "string"
         },
+        "renderedStylesheet": {
+          "type": "string",
+          "description": "The definition's `stylesheet`, copied in when `renderedHtml` is written. A render provider's backend, and Cloud rendering from storage, have no definition to ask, so `@templatical/renderer` emits this when no `getCustomBlockStylesheet` resolver is passed. A resolver, when passed, decides every type, so a stale copy never overrides a live definition."
+        },
         "dataSourceFetched": {
           "type": "boolean"
         }
@@ -1681,6 +1811,10 @@
         },
         "borderRadius": {
           "type": "number"
+        },
+        "backgroundImage": {
+          "$ref": "#/definitions/BackgroundImage",
+          "description": "Image behind the band; `styles.backgroundColor` is its fallback."
         }
       },
       "required": [
@@ -1690,7 +1824,7 @@
         "type"
       ],
       "additionalProperties": false,
-      "description": "Layout-only band rendered as `mj-wrapper`. The block is the band: `styles.backgroundColor` / `styles.padding` / `borderRadius` map to the wrapper. Legal in layout only this ship."
+      "description": "Layout-only band rendered as `mj-wrapper`. The block is the band: `styles.backgroundColor` / `styles.padding` / `borderRadius` / `backgroundImage` map to the wrapper. Legal in layout only."
     },
     "TemplateSettings": {
       "type": "object",