@se-studio/contentful-cms 3.9.2 → 3.9.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/contentful-cms Changelog
 
+## 3.9.4
+
+### Patch Changes
+
+- 6eea7fc: Teach create-from-document and source-readiness to fork designer HTML / custom interaction onto htmlComponent (mixed pages) instead of always mapping copy onto registered card types.
+
+## 3.9.3
+
+### Patch Changes
+
+- Bump zod 4.5.4 and tsx 4.23.13 on packages that declare them.
+
 ## 3.9.2
 
 ### Patch Changes

package/dist/contentful/cma-user-agent.d.ts

@@ -1,5 +1,5 @@
 /** SDK `application` value. Becomes `app cms-edit/<version>` in X-Contentful-User-Agent. */
-export declare const CMA_APPLICATION = "cms-edit/3.9.2";
+export declare const CMA_APPLICATION = "cms-edit/3.9.4";
 export declare function cmaClientOptions(accessToken: string): {
     accessToken: string;
     application: string;

package/dist/generated/version.d.ts

@@ -1,3 +1,3 @@
 export declare const CMS_EDIT_PACKAGE_NAME = "@se-studio/contentful-cms";
-export declare const CMS_EDIT_VERSION = "3.9.2";
+export declare const CMS_EDIT_VERSION = "3.9.4";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -1,4 +1,4 @@
 // Generated by scripts/generate-embedded-assets.mjs — do not edit manually.
 export const CMS_EDIT_PACKAGE_NAME = "@se-studio/contentful-cms";
-export const CMS_EDIT_VERSION = "3.9.2";
+export const CMS_EDIT_VERSION = "3.9.4";
 //# sourceMappingURL=version.js.map

package/docs/editor-tasks/create-from-document.md

@@ -14,8 +14,9 @@
 
 ## Prerequisites
 
-- Fetch package materials (Google Drive MCP, paste, Figma link, zip, production ref, or mix)
+- Fetch package materials (Google Drive MCP, paste, Figma link, zip, production ref, **or designer HTML**)
 - Read `cms-edit://customer/components-index`, `routing`, and for articles **`articles`**
+- **Designer HTML / interactive prototype:** if `cms-edit://customer/task-create-html-component` (or another site HtmlComponent playbook) exists, **switch to that playbook** and stop this one. Otherwise follow the HtmlComponent fork in Phase 2 — do not flatten custom CSS/JS/scroll into registered cards.
 - **Non-trivial packages:** complete **`task-source-readiness-review`** first (inventory → beat sheet → verdict → light human yes)
 
 ## Steps
@@ -38,8 +39,12 @@
 ### Phase 2 — Plan and create
 
 1. Read `cms-edit://customer/tasks-index` and relevant playbooks (`articles` / `pages`).
-2. Map soft-proof beats to **registered** component types only — prefer **source order** over CMS convenience (do not invent side-by-side pairs unless the source is a true pair).
-3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list, gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed.
+2. **Per-section mapping:**
+   - If **layout and interaction** match a registered type (e.g. FAQ accordion → FAQs), use that type.
+   - If the source is custom HTML/JS, sticky/scroll, diagrams, or a private layout shell, and this space has `htmlComponent`, map that beat to **`htmlComponent`** — not cards/lists that only match the copy.
+   - Mixed pages are expected. Merge consecutive custom sections that share CSS/JS/sticky into **one** HtmlComponent. Do not emit one HtmlComponent per `<section>`.
+   - Prefer **source order** over CMS convenience (do not invent side-by-side pairs unless the source is a true pair).
+3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list (registered **and** `htmlComponent` where needed), gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed. For HtmlComponent beats: extract `data:` media first; run `schema htmlComponent` for this space’s field IDs (`html` vs `htmlContent`).
 4. For pages: `list --type template` — pick template; check template `preContent` / `postContent` so heroes are not duplicated.
 5. For articles: resolve `articleType`; apply site SEO and lab rules from `articles` playbook.
 6. Build `create from-json` payload **or** prefer incremental `open` → `add` / `set` / `rtf` for large multi-block work. Link visuals using the pack map from Phase 1.
@@ -64,6 +69,7 @@ Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc`
 - Asset upload without reuse check (see **Media** capability)
 - Mid-article ffmpeg / Drive size thrash — use **`task-media-pipeline-prepare`** first
 - Inventing layout, section titles, or pair collections absent from the source
+- Flattening designer HTML / custom interaction into registered cards because the copy looks like a card grid
 
 ## Related resources
 
@@ -75,3 +81,4 @@ Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc`
 - `task-create-page`
 - `task-media-reuse-and-upload`
 - `task-preview-verify`
+- Site HtmlComponent playbook when present (`cms-edit://customer/task-create-html-component`)

package/docs/editor-tasks/source-readiness-review.md

@@ -45,11 +45,11 @@ If title, order, or hero asset **conflict** and the user has not decided → **N
    |---|------|-------------------|-----------------------------------|----------------------|
    | 1 | … | … | … | … |
 
-3. **Build beat sheet** — ordered narrative + visual beats mapped to **registered** component/collection types only (from `components-index` / site playbook). Prefer **source order** over CMS convenience.
+3. **Build beat sheet** — ordered narrative + visual beats. For each beat: use a **registered** component/collection type when **layout and interaction** match (`components-index` / site playbook). If the source is designer HTML, custom CSS/JS, sticky/scroll, or a diagram that no registered type can reproduce, map to **`htmlComponent`** when that type exists in the space (and follow a site `task-create-html-component` playbook if present). Mixed stacks are valid. Merge consecutive custom HTML beats that share CSS/JS. Prefer **source order** over CMS convenience.
 4. **Score verdict** using the threshold below.
 5. **Post one-screen soft-proof** — numbered final `content` (or page stack) order + gap list + verdict.
 6. **Ask for a light human confirm** — accept **yes** / **go** / **proceed** (or equivalent). Do not build on silence if the package is non-trivial.
-7. On **GO** or **GO-WITH-GAPS** + yes → hand off to `task-create-from-document` / `task-create-article` / `task-create-page` with the soft-proof as the plan.
+7. On **GO** or **GO-WITH-GAPS** + yes → hand off to `task-create-html-component` (if the site has it and the source is designer HTML), otherwise `task-create-from-document` / `task-create-article` / `task-create-page` with the soft-proof as the plan.
 8. On **NO-GO** → stop; list what is blocking (do not invent structure to unblock).
 
 ## Gap threshold
@@ -75,7 +75,7 @@ If title, order, or hero asset **conflict** and the user has not decided → **N
 ## Faithful structure rules
 
 1. **Do not rewrite copy** — structure and place only; flag issues for the human.
-2. **Design sequence beats CMS convenience** — do not invent pair/side-by-side collections unless the source is a true pair.
+2. **Design sequence beats CMS convenience** — do not invent pair/side-by-side collections unless the source is a true pair. If a beat is custom HTML/JS/scroll/diagram and `htmlComponent` exists, **remap that beat to `htmlComponent` and continue** (GO / GO-WITH-GAPS) — do not NO-GO the package and do not flatten it onto cards.
 3. **Placeholders beat reordering** — keep the slot; label the gap (do not drop missing beats and renumber silently).
 4. **Merge continuous prose** — do not split body-only blocks without a layout reason (art, quote, or design break between).
 5. **Hero / template owns page H1** when the site template provides it — body headings only when the source has section titles.
@@ -114,3 +114,4 @@ Copy: unchanged from source (list any human decisions only)
 - `task-media-pipeline-prepare`
 - `task-media-reuse-and-upload`
 - `task-preview-verify`
+- Site `task-create-html-component` when present

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.9.2",
+  "version": "3.9.4",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",
@@ -68,7 +68,7 @@
     "dotenv": "^17.4.2",
     "jose": "^6.2.10",
     "picocolors": "^1.1.1",
-    "zod": "^4.5.2"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.11",