@fluid-app/fluid-cli-theme-dev 0.1.26 → 0.1.27

package/dist/skills/themes-review/SKILL.md

@@ -331,6 +331,7 @@ touches them. Read the matching file when you hit its topic:
 - **[Editor attributes](references/editor-attributes.md)** — `section.fluid_attributes` / `block.fluid_attributes`.
 - **[FairShare attributes](references/fairshare-attributes.md)** — `data-fluid-*` cart / add-to-cart behavioral attributes + the CDN script.
 - **[Performance](references/performance.md)** — `asset_url` in loops, render hygiene.
+- **[Media rendering](references/media-tag.md)** — the `media_tag` filter for responsive, format-negotiated images and video; when raw `<img>`/`<video>` is wrong.
 - **[Security & accessibility](references/security-accessibility.md)** — escaping user content, alt text, semantic clickables.
 - **[Dead code](references/dead-code.md)** — unused sections/components/assets, unhandled block types.
 - **[CSS / JS hygiene](references/css-js-hygiene.md)** — co-located stylesheet deprecation, inline `<style>`/`<script>` thresholds, `defer`.
@@ -619,6 +620,7 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 - [ ] No user-visible literal text in markup (use `text`/`textarea`/`richtext`)
 - [ ] No hardcoded colors in styles (use `color` / `color_background` or a global token)
 - [ ] No hardcoded image URLs (use `image_picker` or upload to `assets/`)
+- [ ] Setting/resource images and videos render through `| media_tag` (not hand-rolled `<img>`/`<video>`)
 - [ ] No external CDN URLs for theme-owned assets
 - [ ] No hardcoded `href` to fixed paths the company might want to change (use `url`)
 

package/dist/skills/themes-review/references/blocks-vs-sections.md

@@ -103,9 +103,7 @@ Rendering:
 <div class="features features--cols-{{ section.settings.columns }}">
   {%- for block in section.blocks -%}
     <article class="feature" {{ block.fluid_attributes }}>
-      {%- if block.settings.icon != blank -%}
-        <img src="{{ block.settings.icon }}" alt="{{ block.settings.title | escape }}" />
-      {%- endif -%}
+      {{ block.settings.icon | media_tag: alt: block.settings.title }}
       <h3>{{ block.settings.title }}</h3>
       <p>{{ block.settings.body }}</p>
     </article>

package/dist/skills/themes-review/references/dynamism.md

@@ -54,9 +54,7 @@ Every one of those values — background, padding, heading text, body text, imag
 <section style="background:{{ s.bg_color }};padding:{{ s.section_pad }};">
   <h2 style="color:{{ s.text_color }};">{{ s.heading | default: 'Our Bestsellers' }}</h2>
   <p>{{ s.body }}</p>
-  {%- if s.banner_image != blank -%}
-    <img src="{{ s.banner_image }}" alt="{{ s.heading | escape }}" />
-  {%- endif -%}
+  {{ s.banner_image | media_tag: alt: s.heading }}
   {%- if s.show_cta -%}
     <a href="{{ s.cta_url }}" class="btn">{{ s.cta_label }}</a>
   {%- endif -%}
@@ -70,6 +68,7 @@ Every one of those values — background, padding, heading text, body text, imag
 | User-visible literal text in markup (heading, paragraph, button label) | `should`                                        | Should be a `text` / `textarea` / `richtext` setting.                                             |
 | Hardcoded colors (`#0a0a0a`, `rgb(...)`, `red`) in style/attribute     | `should`                                        | Should be a `color` or `color_background` setting.                                                |
 | Hardcoded image URL (external CDN, hardcoded path)                     | `blocker` if external CDN, `should` if internal | External CDNs can break, get blocked, or change. Upload to `assets/` or expose as `image_picker`. |
+| Setting/resource image rendered with a raw `<img>` instead of `\| media_tag` | `should`                            | Misses responsive `srcset` + format negotiation. See [Media rendering](media-tag.md).            |
 | Hardcoded `href` to a fixed page or `?sort=popular`-style URL          | `should`                                        | Use a `url` setting.                                                                              |
 | Hardcoded counts (`limit: 6`, `limit: 12`) in `for` loops              | `nit` → `should`                                | Expose as a `range` setting if the company might want to change density.                          |
 | Boolean branches with no user toggle (`{% if true %}`)                 | `should`                                        | Either delete or expose as a `checkbox`.                                                          |

package/dist/skills/themes-review/references/media-tag.md

@@ -0,0 +1,67 @@
+# Media rendering — `media_tag`
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+Render every setting- or resource-backed image and video with the `media_tag` filter. It turns an image or video into a complete, responsive HTML element — `srcset`, WebP/AVIF negotiation, `loading`, `decoding="async"`, and `alt` — so a hand-rolled `<img>` / `<video>` in a section is almost always the wrong call.
+
+Docs: <https://docs.fluid.app/docs/themes/media-tag>
+
+## Contents
+
+- 1. The rule
+- 2. Options
+- 3. Video
+- 4. What it does *not* replace
+
+### 1. The rule
+
+**`should`.** A raw `<img src="{{ ... }}">` or `<video>` that renders an `image` / `image_picker` / `video_picker` / `media_picker` setting, or a resource image (`product.image`, `collection.image`, …), should be `| media_tag`. Hand-rolled markup ships one fixed-size original — no responsive `srcset`, no format negotiation — which bloats the download and hurts LCP, and forces you to remember `loading` / `decoding` / `alt` every time.
+
+```liquid
+{%- comment -%} Bad: fixed original, manual (easy-to-forget) attributes {%- endcomment -%}
+<img src="{{ section.settings.banner_image }}" alt="{{ section.settings.heading | escape }}" loading="lazy" decoding="async" />
+
+{%- comment -%} Good: responsive, format-negotiated, accessible — one filter {%- endcomment -%}
+{{ section.settings.banner_image | media_tag: sizes: '(max-width: 768px) 100vw, 1200px', alt: section.settings.heading }}
+```
+
+`media_tag` escapes its own output, so do **not** wrap the setting in `| escape` yourself. It renders nothing on blank input, so the `{%- if image != blank -%}` guard is optional — keep it only when surrounding markup must be suppressed too.
+
+### 2. Options
+
+Pass options as filter arguments. Anything not in this table becomes a plain HTML attribute (`class`, `id`, `data-*`).
+
+| Option    | Default             | Purpose                                                                    |
+| --------- | ------------------- | -------------------------------------------------------------------------- |
+| `sizes`   | `100vw`             | Browser sizing hint — set it to the real rendered width.                   |
+| `widths`  | `400,800,1200,1600` | `srcset` breakpoints.                                                      |
+| `width`   | —                   | Fixed display width; emits a 2× retina `srcset`.                           |
+| `height`  | —                   | Layout stability (avoids CLS).                                             |
+| `quality` | `80`                | 1–100.                                                                     |
+| `format`  | `auto`              | WebP/AVIF negotiation.                                                     |
+| `crop`    | —                   | Focus point.                                                               |
+| `loading` | `lazy`              | Use `eager` for the hero / above-the-fold image — `lazy` there delays LCP. |
+| `alt`     | image's alt text    | Set it for `*_picker` settings; `alt: ''` for decorative.                  |
+
+```liquid
+{%- comment -%} Fixed-width logo, retina srcset {%- endcomment -%}
+{{ section.settings.logo | media_tag: width: 240, alt: 'Logo' }}
+
+{%- comment -%} Hero — eager so it doesn't delay LCP {%- endcomment -%}
+{{ section.settings.hero | media_tag: sizes: '100vw', loading: 'eager', alt: section.settings.heading }}
+```
+
+### 3. Video
+
+A video URL (`.mp4` / `.mov` / `.webm` / `.m4v`) or video object renders a `<video>`. Options: `autoplay`, `loop`, `muted`, `controls`, `poster`, `format` (default `mp4`), `quality`.
+
+```liquid
+{{ section.settings.bg_video | media_tag: autoplay: true, loop: true, muted: true }}
+```
+
+### 4. What it does *not* replace
+
+- **Static theme assets** (`'logo.svg' | asset_url`) are not ImageKit media — `media_tag` passes non-ImageKit URLs through as a plain tag, so `asset_url` + a plain `<img>` stays correct for files shipped in `assets/`.
+- **`alt` judgement** is still yours — `media_tag` defaults `alt` from the image, but `*_picker` settings carry none, so pass one (or `alt: ''` for decorative). The alt rule in [security & accessibility](security-accessibility.md) still applies.
+
+---

package/dist/skills/themes-review/references/security-accessibility.md

@@ -41,15 +41,17 @@
 
 ### 1. Missing `alt` on images
 
+Render the image with `| media_tag` (see [Media rendering](media-tag.md)) and pass `alt`:
+
 ```liquid
-{%- comment -%} Bad {%- endcomment -%}
-<img src="{{ product.featured_image }}" />
+{%- comment -%} Bad: image_picker carries no stored alt, so this ships alt-less {%- endcomment -%}
+{{ section.settings.image | media_tag }}
 
 {%- comment -%} Good {%- endcomment -%}
-<img src="{{ product.featured_image }}" alt="{{ product.title | escape }}" />
+{{ section.settings.image | media_tag: alt: section.settings.heading }}
 ```
 
-Decorative images: `alt=""`.
+`media_tag` defaults `alt` from a resource image (`product.featured_image`), but `*_picker` settings carry none — pass one explicitly. Decorative images: `alt: ''`.
 
 ### 2. Heading hierarchy
 
@@ -61,10 +63,10 @@ A clickable `<div>` is `blocker`. Use `<button>` for actions, `<a href>` for nav
 
 ### 4. `decoding="async"` and `loading="lazy"`
 
+`| media_tag` applies `decoding="async"` and `loading="lazy"` for you — don't hand-roll them. For hero/above-the-fold images pass `loading: 'eager'`, since lazy loading there delays LCP:
+
 ```liquid
-<img src="..." alt="..." loading="lazy" decoding="async" />
+{{ section.settings.hero | media_tag: loading: 'eager', alt: section.settings.heading }}
 ```
 
-Don't set `loading="lazy"` on hero/above-the-fold images — it delays LCP.
-
 ---

package/dist/skills/themes-review/references/setting-types.md

@@ -41,6 +41,8 @@ These are the canonical setting types. **Any `type:` value not in this list is r
 
 ### Visual & media
 
+Render `image` / `image_picker` / `video_picker` / `media_picker` values with the `media_tag` filter, not a hand-rolled `<img>`/`<video>` — see [Media rendering](media-tag.md).
+
 | `type`             | Notes                                                             |
 | ------------------ | ----------------------------------------------------------------- |
 | `color`            | Single color picker.                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "files": [
     "dist",
@@ -38,10 +38,10 @@
     "jest": "^29.7.0",
     "tsdown": "^0.21.0",
     "typescript": "^5",
-    "@fluid-app/api-client-core": "0.1.0",
+    "@fluid-app/themes-api-client": "0.1.0",
     "@fluid-app/typescript-config": "0.0.0",
-    "@fluid-app/theme-schema": "0.1.0",
-    "@fluid-app/themes-api-client": "0.1.0"
+    "@fluid-app/api-client-core": "0.1.0",
+    "@fluid-app/theme-schema": "0.1.0"
   },
   "engines": {
     "node": ">=18.0.0"