@se-studio/skills 1.7.13 → 1.7.14

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @se-studio/skills
 
+## 1.7.14
+
+### Patch Changes
+
+- 531e8ca: Add HtmlComponent `externalScripts` so editors can list allowlisted script URLs that load with next/script before customJs.
+  
+  Same-origin `/html-components/….js` is always allowed; extra HTTPS hosts are opt-in via `htmlComponentExternalScriptHosts`. Run migration 28 on each customer space after publishing these packages.
+  
+  HSD follow-up: bump packages, run 28 on space `gqa3p93n5wse`, set the readiness HtmlComponent to `["/html-components/specialized-transport-readiness/jspdf.umd.min.js"]`, remove the `createElement('script')` loader from `jsContent`, and pass `externalScripts` through the dual-read converter if it is still in use.
+
 ## 1.7.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.7.13",
+  "version": "1.7.14",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/references/contentful-cms-cms-guidelines/html-component-authoring.md

@@ -51,6 +51,7 @@ Without this import the safelist has no effect and the spacing classes in the Co
 | `rawHtml` | ✓ | Text | The HTML markup. Use Tailwind classes; never inline `style=` for colours/typography/layout. |
 | `customCss` | — | Text | Scoped CSS. Rules are automatically prefixed with `[data-hc-id="<id>"]` — they cannot pollute other components. Use for responsive layout (`@media` queries), `:hover`, `::before`/`::after`, and any utility class not in the confirmed-safe list. |
 | `customJs` | — | Text | JavaScript loaded via Next.js `<Script>`. A `hcRoot` variable pointing to this component's root element is automatically injected — use it to scope all queries. Use sparingly. |
+| `externalScripts` | — | List of URLs | Allowlisted script URLs loaded with `next/script` **before** `customJs`. Same-origin `/html-components/….js` always; extra HTTPS hosts only if the site sets `htmlComponentExternalScriptHosts`. Max 10. Do not paste CDN tags into HTML. |
 | `markdownContent` | — | Text | Plain text for search indexing. **Always fill this** so the component appears in site search. |
 | `isHero` | — | Boolean | `true` if the HTML contains an `<h1>`. Moves this block to the top of the page content flow. |
 | `fullWidth` | — | Boolean | `true` for edge-to-edge (full-bleed) layouts that break out of the column grid. |
@@ -250,6 +251,13 @@ var section = document.querySelector('[data-hc-id]');
 - Avoid `document.getElementById` unless the ID is guaranteed unique across the whole page.
 - Default `scriptStrategy` is `afterInteractive` — runs after page hydration. Use `lazyOnload` for non-critical third-party widgets.
 
+Put third-party libraries in **`externalScripts`**, not `createElement('script')` inside `customJs`. Allowed values:
+
+- Same-origin paths matching `/html-components/` + a `.js` filename (no `..`, no query string).
+- HTTPS URLs whose hostname is listed in `CmsRendererConfig.htmlComponentExternalScriptHosts` (default empty). Disallowed URLs are not loaded (preview/dev logs a warning).
+
+The renderer waits until those scripts have loaded (`next/script` `onReady`) before running `customJs`. The same URL on two HtmlComponents shares one `next/script` id (`hc-ext-<hash>`). If the site has a Content-Security-Policy, allowlisted hosts must match `script-src`.
+
 ---
 
 ## Common Patterns

package/skills/contentful-cms-core/SKILL.md

@@ -70,7 +70,7 @@ cms-edit open --include-chrome --page-slug /pricing
 
 `open` / `peek` fetch the page (or article) tree and the template entry, but **not** template `menu` / `footer` / navigation. Edit nav with `nav open`. Pass `--include-chrome` only when you need those trees.
 
-**Flat lookup flags:** provide **exactly one** primary flag per `open` / `resolve` / `nav open`. See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
+**Flat lookup flags:** provide **exactly one** primary flag per `open` / `peek` / `resolve`. `nav open` uses **`--nav-id` or `--nav-name` only** (not `--id`). See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
 
 ### Step 2: Read the snapshot
 
@@ -399,8 +399,9 @@ JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?,
 ## Navigation
 
 ```bash
-# Open a navigation entry (navigation uses `name`, not slug)
+# Open a navigation entry (not --id). Navigation uses `name`, not slug.
 cms-edit nav open --nav-name "Main navigation"
+cms-edit nav open --nav-id <navigation-entry-id>
 
 # Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
@@ -409,11 +410,17 @@ cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
 # Link an existing NavigationItem (share items across navigations)
 cms-edit nav add --existing-id <navigationItem-entry-id>
 
-# Clone a navigation (duplicates all items)
+# Clone a navigation (first-level items only; nested children stay shared)
 cms-edit nav clone <source-nav-id>
 cms-edit nav clone <source-nav-id> --label "LP Nav" --slug lp-nav
 ```
 
+Template **`menu`** is site-wide. **`page.menu`** overrides one page. Header CTAs are often nested under a wrapper and **shared**. Before `set` on a nav item, ask whether the change is global or page-specific. Page-specific: new NavigationItem + cloned/new menu on `page.menu` — do not mutate the shared entry.
+
+`peek` is one-shot. `open` / `nav open` persist. `preview urls /slug` follows that slug even if session `_mcp` is another page.
+
+The items array field may be `entries`, `items`, or `navigationItems` — inspect `read @root` before `set @root … --links`.
+
 ## Create New Entries
 
 ```bash

package/skills/contentful-cms-navigation/SKILL.md

@@ -24,8 +24,10 @@ Use this skill when creating or editing **navigation** entries and their items i
    cms-edit nav add --existing-id <id> --after @c1
    ```
 4. **Set** nav item fields (use snapshot refs): `cms-edit set @c1 title "New label"`, `cms-edit set @c1 internal <page-entry-id> --link`, `cms-edit set @c1 link "https://..."`.
-5. **Set the items array directly** (e.g. to replace all items at once):
+5. **Set the items array directly** (e.g. to replace all items at once). The array field is **`entries`**, **`items`**, or **`navigationItems`** depending on the space — use `snapshot` / `read @root` to see which exists. Do not invent `items` on spaces that use `entries`:
    ```bash
+   cms-edit set @root entries <id1>,<id2>,<id3> --links
+   # generic spaces:
    cms-edit set @root items <id1>,<id2>,<id3> --links
    ```
 6. **Remove** an item: `cms-edit remove @cN`
@@ -33,7 +35,7 @@ Use this skill when creating or editing **navigation** entries and their items i
 
 ## Cloning a navigation
 
-To duplicate a navigation and all its items (e.g. for a landing page variant):
+To duplicate a navigation (e.g. for a page-specific menu via `page.menu`):
 
 ```bash
 cms-edit nav clone <source-nav-id>
@@ -41,7 +43,23 @@ cms-edit nav clone <source-nav-id>
 cms-edit nav clone <source-nav-id> --label "LP Navigation" --slug lp-nav
 ```
 
-This creates new copies of every NavigationItem and links them into the new navigation. Prints the new navigation ID and an `open` command.
+Clone copies **first-level** NavigationItem entries. Nested `navigationItems` (children of a “Nav items” wrapper, often the header CTA) stay as **shared links**. Editing a nested child on the copy edits every menu that links it.
+
+`--label` is written to `name` and/or `adminLabel` and/or `label` **only when those fields exist** on the navigation content type.
+
+## Shared vs page-specific edits
+
+- Template **`menu`** is site-wide. **`page.menu`** (and article/type menu fields where present) override one page.
+- The header CTA is often the **last** item and may be nested under a wrapper.
+- **Before `set` on a nav item:** ask whether the change is **global** or **page-specific**.
+  - Global → edit the shared NavigationItem.
+  - Page-specific → new NavigationItem + link it on a cloned (or new) menu, then set `page.menu`. Do not mutate the shared entry.
+
+## Sessions vs peek / preview
+
+- `peek` is one-shot (no session). `open` and `nav open` persist.
+- `cms-edit nav open --nav-id <id>` or `--nav-name "…"` — **not** `--id`.
+- `preview urls /slug` follows that slug even if a leftover MCP session is another page (`sessionRootIgnored` in JSON). Use `--session` to isolate concurrent work.
 
 ## Session refs
 
@@ -79,6 +97,14 @@ cms-edit set @root footer <footer-nav-id> --link
 cms-edit save
 ```
 
+Page-specific override:
+
+```bash
+cms-edit open --page-slug /caregiver-hub
+cms-edit set @root menu <cloned-or-new-nav-id> --link
+cms-edit save
+```
+
 ## Related skills
 
 See the **core** skill for session, refs, and all commands. For templates that use menu/footer see the **templates** skill.