webcake-storefront-mcp 1.16.0 → 1.17.0

package/dist/builder/guide.js

@@ -36,7 +36,26 @@ children with a grid:
 - each child config also has \`rowStart/rowEnd\` (1-based grid lines),
   \`constraintX\` (['left'|'right'|'centerLeft']), \`constraintY\` (['top'|'bottom'|'centerTop']).
 new_section does ALL of this for you: pass children and they are stacked one row each in
-the centre column. To build multi-column layouts, nest a container child with its own grid.
+the centre column.
+
+## Multi-column rows (cards side by side) — USE THIS, real pages are full of them
+A plain vertical stack looks like a blog post, not a designed page. Feature cards,
+category tiles, footer columns, a text+image hero — all are HORIZONTAL rows. Two ways:
+- new_row(children=[colA, colB, colC]) → a container whose children sit SIDE BY SIDE in
+  equal columns. Place the returned node as a child of a section.
+- Inside new_section, add \`layout:"row"\` to a CONTAINER child spec and its children become
+  columns: \`{ type:"container", layout:"row", children:[ {..}, {..}, {..} ] }\`.
+Rows are RESPONSIVE automatically: finalizeForRender collapses them on small screens
+(default tablet=2 columns, mobile=1) so cards never shrink to slivers — override with
+\`collapse:{bp3:2,bp4:1}\`. Uneven columns via \`colWidths\` (e.g. a 2:1 text/image split:
+\`colWidths:[{unit:'fr',value:2},{unit:'fr',value:1}]\`), spacing via \`columnGap\`/\`rowGap\`.
+Each column is usually a \`container\` holding its own stacked children (image + title +
+text). Example feature row:
+\`new_row(children=[
+  { type:"container", children:[ {type:"image",opts:{...}}, {type:"text",opts:{text:"Giao nhanh"}} ] },
+  { type:"container", children:[ {type:"image",opts:{...}}, {type:"text",opts:{text:"Chất lượng"}} ] },
+  { type:"container", children:[ {type:"image",opts:{...}}, {type:"text",opts:{text:"Bảo hành"}} ] },
+])\`
 
 ## Where layout/style live: per-breakpoint keys (NOT \`runtime\`)
 new_section / new_element emit a temporary \`runtime: { style, config }\`. That is a

package/dist/builder/page.js

@@ -84,6 +84,68 @@ export function stackChildren(container, children, opts = {}) {
     container.children = children;
     return container;
 }
+const ROW_PLACEHOLDER_ROW = () => ({ unit: "min/max", min: { unit: "px", absValue: 50 }, max: { unit: "max-c" } });
+/** Default responsive collapse for a multi-column row: full columns on desktop/laptop,
+ *  2 columns on tablet, 1 column on mobile. `null` = keep the full column count. */
+const ROW_COLLAPSE_DEFAULT = { bp1: null, bp2: null, bp3: 2, bp4: 1 };
+/**
+ * Lay children out HORIZONTALLY — side by side in one grid row — the way real BuilderX
+ * pages build feature cards, category tiles, footer columns, 2-col hero, etc. The grid is
+ * `Nx1` with N equal `fr` columns and each child placed in its own column. Values go to
+ * `runtime` plus `__row`/`__cell` markers that finalizeForRender() reads to emit a
+ * RESPONSIVE grid per breakpoint (it auto-collapses to fewer columns on tablet/mobile so
+ * the row never renders as cramped slivers).
+ */
+export function rowChildren(container, children, opts = {}) {
+    const cols = children.length || 1;
+    const colWidths = opts.colWidths && opts.colWidths.length === cols
+        ? opts.colWidths
+        : Array.from({ length: cols }, () => ({ unit: "fr", value: 1 }));
+    const collapse = { ...ROW_COLLAPSE_DEFAULT, ...(opts.collapse || {}) };
+    const columnGap = opts.columnGap ?? 24;
+    const rowGap = opts.rowGap ?? 24;
+    const meta = { cols, count: children.length, collapse, columnGap, rowGap };
+    container.runtime = container.runtime || {};
+    container.runtime.config = {
+        ...(container.runtime.config || {}),
+        grid: `${cols}x1`,
+        columns: colWidths,
+        rows: [ROW_PLACEHOLDER_ROW()],
+        columnGap,
+        rowGap,
+        heightUnit: "auto",
+        __row: meta,
+    };
+    children.forEach((child, i) => {
+        child.runtime = child.runtime || {};
+        child.runtime.config = {
+            ...(child.runtime.config || {}),
+            columnStart: i + 1,
+            columnEnd: i + 2,
+            rowStart: 1,
+            rowEnd: 2,
+            constraintX: (child.runtime.config && child.runtime.config.constraintX) || ["centerLeft"],
+            constraintY: (child.runtime.config && child.runtime.config.constraintY) || ["top"],
+            loaded: true,
+            __cell: { index: i, ...meta },
+        };
+    });
+    container.children = children;
+    return container;
+}
+/** Build a standalone multi-column ROW container from child specs (each laid side by side).
+ *  Used by the new_row tool; inside new_section pass `layout:"row"` on a container spec. */
+export function buildRow(childSpecs = [], opts = {}) {
+    const container = buildElement("container", opts.containerOpts || {});
+    const children = childSpecs.map((spec) => buildFromSpec(spec));
+    return rowChildren(container, children, opts);
+}
+/** How many columns a row shows at a given breakpoint (clamped to its real column count). */
+function colsForBp(meta, bp) {
+    const c = meta.collapse ? meta.collapse[bp] : null;
+    const k = c == null ? meta.cols : Math.min(c, meta.cols);
+    return Math.max(1, k);
+}
 /**
  * Build a ready-to-place section from a list of child specs.
  * Each spec: { type, opts?, children? } where children is a nested array of specs.
@@ -118,7 +180,19 @@ function buildFromSpec(spec) {
     const node = buildElement(spec.type, spec.opts || {});
     if (Array.isArray(spec.children) && spec.children.length) {
         const kids = spec.children.map((c) => buildFromSpec(c));
-        stackChildren(node, kids);
+        // `layout:"row"` lays the children out side by side (responsive); default is a
+        // top-to-bottom vertical stack. rowGap/columnGap/colWidths/collapse tune the layout.
+        if (spec.layout === "row") {
+            rowChildren(node, kids, {
+                columnGap: spec.columnGap,
+                rowGap: spec.rowGap,
+                colWidths: spec.colWidths,
+                collapse: spec.collapse,
+            });
+        }
+        else {
+            stackChildren(node, kids, { rowGap: spec.rowGap });
+        }
     }
     return node;
 }
@@ -193,9 +267,14 @@ function expandNodeToBreakpoints(node) {
         const baseStyle = rt.style || {};
         const baseConfig = { ...(rt.config || {}), loaded: true };
         const isSection = node.type === "section";
+        const rowMeta = baseConfig.__row; // this node is a multi-column row container
+        const cellMeta = baseConfig.__cell; // this node is a cell inside a row
         for (const [bp, [minW]] of Object.entries(BREAKPOINTS)) {
             const style = clone(baseStyle);
             const config = clone(baseConfig);
+            // Internal build-time markers never get persisted.
+            delete config.__row;
+            delete config.__cell;
             if (isSection) {
                 const g = genGridByBp(minW);
                 const sectionRows = baseConfig.rows && baseConfig.rows.length ? clone(baseConfig.rows) : clone(g.rows);
@@ -204,6 +283,29 @@ function expandNodeToBreakpoints(node) {
                 config.grid = `3x${sectionRows.length}`;
                 config.heightUnit = config.heightUnit || "auto";
             }
+            // A multi-column row collapses to fewer columns on smaller screens so cards never
+            // shrink to slivers: recompute the grid + this container's columns per breakpoint.
+            if (rowMeta) {
+                const k = colsForBp(rowMeta, bp);
+                const nrows = Math.ceil(rowMeta.count / k);
+                config.columns =
+                    k === rowMeta.cols && Array.isArray(baseConfig.columns) && baseConfig.columns.length === k
+                        ? clone(baseConfig.columns)
+                        : Array.from({ length: k }, () => ({ unit: "fr", value: 1 }));
+                config.rows = Array.from({ length: nrows }, () => ROW_PLACEHOLDER_ROW());
+                config.grid = `${k}x${nrows}`;
+                config.heightUnit = config.heightUnit || "auto";
+            }
+            // A cell repositions itself into the collapsed grid (wraps to a new row as needed).
+            if (cellMeta) {
+                const k = colsForBp(cellMeta, bp);
+                const c = cellMeta.index % k;
+                const r = Math.floor(cellMeta.index / k);
+                config.columnStart = c + 1;
+                config.columnEnd = c + 2;
+                config.rowStart = r + 1;
+                config.rowEnd = r + 2;
+            }
             node[bp] = { style, config };
         }
         delete node.runtime;

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.17.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "New new_row tool builds a multi-column responsive row container where child elements are placed side by side (left to right); the row auto-collapses…",
+    "vi": "Tool mới new_row tạo một container đa cột responsive với các phần tử con được đặt nằm ngang cạnh nhau (từ trái sang phải); hàng tự động thu gọn…"
+  },
   {
     "v": "1.16.0",
     "d": "24/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "New restore_file_version tool rolls a CMS file back to a saved version in one step: it reads the chosen version's content (via get_file_versions)…",
     "vi": "Tool mới restore_file_version khôi phục CMS file về một phiên bản đã lưu chỉ trong một bước: đọc nội dung phiên bản được chọn (qua…"
-  },
-  {
-    "v": "1.12.1",
-    "d": "24/06/2026",
-    "type": "Fixed",
-    "en": "save_file_version and get_file_versions both sent the parameter as cms_file_id, but the backend reads file_id; versions were saved unlinked to any…",
-    "vi": "save_file_version và get_file_versions đều gửi tham số dưới key cms_file_id, trong khi backend đọc file_id; các phiên bản được lưu mà không liên kết…"
   }
 ]

package/dist/tools/builder.js

@@ -3,12 +3,17 @@ import { BUILD_GUIDE } from "../builder/guide.js";
 import { listElements, getElement, buildElement } from "../builder/catalog.js";
 import { describeEventsCatalog } from "../builder/events.js";
 import { describeBindingsCatalog } from "../builder/bindings.js";
-import { buildSection, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
+import { buildSection, buildRow, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
 // Recursive spec for new_section / build_page children.
 const elementSpec = z.object({
     type: z.string().describe("Element type (see list_elements)"),
     opts: z.record(z.any()).optional().describe("Factory opts: { style, config, specials, text, src, width, height, ... }"),
     children: z.array(z.any()).optional().describe("Nested child specs (same shape) for container types"),
+    layout: z.enum(["row", "column"]).optional().describe("How this node's children are laid out: 'row' = side by side (responsive columns, auto-collapses on tablet/mobile), 'column' = stacked top-to-bottom (default). Use 'row' on a container to make feature cards / category tiles / footer columns / 2-col hero."),
+    rowGap: z.number().optional().describe("Vertical gap (px) between stacked children / wrapped rows"),
+    columnGap: z.number().optional().describe("Horizontal gap (px) between columns (layout:'row' only)"),
+    colWidths: z.array(z.any()).optional().describe("layout:'row' only — explicit per-column unit objects (length = #children), e.g. [{unit:'fr',value:2},{unit:'fr',value:1}] for a 2:1 split. Default: equal columns."),
+    collapse: z.record(z.number()).optional().describe("layout:'row' only — columns to show per breakpoint, e.g. {bp3:2,bp4:1}. Default: tablet 2, mobile 1."),
 });
 function parseSource(src) {
     if (src == null)
@@ -48,6 +53,24 @@ Example children: [{ "type":"text", "opts":{"text":"Welcome","style":{"fontSize"
         children: z.array(elementSpec).default([]).describe("Child element specs, stacked vertically in the section"),
         section_opts: z.record(z.any()).optional().describe("Optional factory opts for the section node itself"),
     }, ({ children, section_opts }) => handle(async () => buildSection(children || [], section_opts || {})));
+    server.tool("new_row", `Build a multi-column ROW container: children laid out SIDE BY SIDE (not stacked).
+This is how real pages build feature cards, category tiles, footer columns, a 2-col hero, etc.
+The row is RESPONSIVE — it auto-collapses to fewer columns on tablet/mobile (default tablet 2, mobile 1) so cards never become cramped slivers.
+Place the returned node as a child inside a section (section children still stack vertically; nest a row for horizontal layout).
+Example children: [{ "type":"container", "children":[{"type":"image","opts":{...}},{"type":"text","opts":{...}}] }, { ... }, { ... }]`, {
+        children: z.array(elementSpec).default([]).describe("Child specs, one per column (laid out left-to-right)"),
+        column_gap: z.number().optional().describe("Horizontal gap (px) between columns (default 24)"),
+        row_gap: z.number().optional().describe("Vertical gap (px) between wrapped rows (default 24)"),
+        col_widths: z.array(z.any()).optional().describe("Explicit per-column unit objects (length = #children), e.g. [{unit:'fr',value:2},{unit:'fr',value:1}]. Default: equal columns."),
+        collapse: z.record(z.number()).optional().describe("Columns to show per breakpoint, e.g. {bp3:2,bp4:1}. Default: tablet 2, mobile 1."),
+        container_opts: z.record(z.any()).optional().describe("Optional factory opts for the row container node itself (e.g. { style:{...} })"),
+    }, ({ children, column_gap, row_gap, col_widths, collapse, container_opts }) => handle(async () => buildRow(children || [], {
+        columnGap: column_gap,
+        rowGap: row_gap,
+        colWidths: col_widths,
+        collapse,
+        containerOpts: container_opts || {},
+    })));
     server.tool("new_page_skeleton", "Return an empty but valid page source: { sections: [] }. Add sections built with new_section, then save with build_page.", {}, () => handle(async () => newPageSkeleton()));
     server.tool("validate_page", "Validate a page source ({ sections: [...] }). Returns errors (block saving: duplicate/missing ids, missing types) and warnings (unknown types, form fields without field_name, dangling event targets) plus stats. Always run this before build_page.", {
         source: z.any().describe("Page source object or JSON string"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",