@jay-framework/wix-media 0.19.6 → 0.20.0

package/agent-kit/designer/wix-media.md

@@ -28,11 +28,28 @@ URL format: `https://static.wixstatic.com/media/{mediaId}/v1/{mode}/{params}/fil
 - **crop** — extract a rectangle at specific coordinates
   `<img src="https://static.wixstatic.com/media/{mediaId}/v1/crop/x_100,y_50,w_800,h_600/file.jpg" alt="" />`
 
+#### Crop + Resize (chained transforms)
+
+Add a `/crop/` segment before `/fill/` (or `/fit/`) to first extract a region, then resize it:
+
+```
+/v1/crop/x_{x},y_{y},w_{cropW},h_{cropH}/fill/w_{outputW},h_{outputH}/file.ext
+```
+
+Example — crop a 2688×1278 region starting at (0, 514), then fill-resize to 1437×683:
+
+```html
+<img src="https://static.wixstatic.com/media/{mediaId}/v1/crop/x_0,y_514,w_2688,h_1278/fill/w_1437,h_683/file.jpg" alt="" />
+```
+
+The crop coordinates refer to the original image pixels. The fill/fit parameters set the final output size.
+
 #### Parameters
 
 - `w_{width}` — target width (1–5000 px)
 - `h_{height}` — target height (1–5000 px)
 - `x_{x},y_{y}` — crop start position (crop mode only)
+- `w_{width},h_{height}` — crop region size (crop mode / chained crop)
 - `q_{quality}` — JPEG quality (1–100)
 
 #### Output format (set via file extension)

package/dist/index.d.ts

@@ -16,9 +16,48 @@ interface MediaFileInfo {
     folderId: string;
     folderName: string;
 }
+interface UploadUrlResult {
+    uploadUrl: string;
+}
+interface WixMediaService {
+    listPublicFiles(): Promise<MediaFileInfo[]>;
+    generateUploadUrl(mimeType: string, fileName: string): Promise<UploadUrlResult>;
+}
 
 declare function generateMediaIndex(files: MediaFileInfo[]): string;
 
+/**
+ * Generate Add Menu items for indexed Wix Media Manager files (Design Log #19 M19.2).
+ */
+
+interface MediaAddMenuInteraction {
+    mode: 'stage-place' | 'reference';
+    persistOnPage?: boolean;
+    stagePromptTemplate?: string;
+}
+interface MediaAddMenuItem {
+    id: string;
+    title: string;
+    category: string;
+    subCategory: string;
+    pluginName: string;
+    packageName: string;
+    thumbnail?: string;
+    prompt: string;
+    interaction?: MediaAddMenuInteraction;
+}
+/** Preview URL for picker chips — raster images, vectors, and SVGs served from Wix CDN. */
+declare function thumbnailUrlForMedia(file: MediaFileInfo): string | undefined;
+declare function buildMediaAddMenuItems(files: MediaFileInfo[]): MediaAddMenuItem[];
+
+declare const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/wix-media.generated.yaml";
+declare function writeGeneratedAddMenuCatalog(projectRoot: string, items: MediaAddMenuItem[]): string;
+
+declare function refreshMediaAddMenuCatalog(projectRoot: string, mediaService: WixMediaService): Promise<{
+    itemCount: number;
+    outputRel: string;
+}>;
+
 declare function setupWixMedia(ctx: PluginSetupContext): Promise<PluginSetupResult>;
 declare function generateWixMediaReferences(ctx: PluginReferencesContext): Promise<PluginReferencesResult>;
 
@@ -32,4 +71,4 @@ declare const uploadPublic: _jay_framework_fullstack_component.JayCliCommand<{
     dryRun?: boolean;
 }, [_jay_framework_fullstack_component.ConsoleContext]>;
 
-export { generateMediaIndex, generateWixMediaReferences, rebuildIndex, setupWixMedia, uploadPublic, validate };
+export { ADD_MENU_GENERATED_REL, buildMediaAddMenuItems, generateMediaIndex, generateWixMediaReferences, rebuildIndex, refreshMediaAddMenuCatalog, setupWixMedia, thumbnailUrlForMedia, uploadPublic, validate, writeGeneratedAddMenuCatalog };

package/dist/index.js

@@ -2,6 +2,7 @@ import { walkElements, resolveBinding } from "@jay-framework/compiler-shared";
 import { parseTemplateParts } from "@jay-framework/compiler-jay-html";
 import * as fs from "fs";
 import * as path from "path";
+import * as yaml from "js-yaml";
 import { registerService, getService } from "@jay-framework/stack-server-runtime";
 import { WIX_CLIENT_SERVICE } from "@jay-framework/wix-server-client";
 import { files, folders } from "@wix/media";
@@ -12,6 +13,8 @@ const WIXSTATIC_MEDIA_RE = /static\.wixstatic\.com\/media\//;
 const V1_TRANSFORM_RE = /\/v1\//;
 const IMAGE_EXTENSIONS_RE = /\.(jpe?g|png|gif|webp|svg|bmp|ico)$/i;
 const SRCSET_UNENCODED_COMMA_RE = /\/v1\/[^/]+\/[^/]*[a-z]_\d+,[a-z]_\d+/;
+const WIDTH_PARAM_RE = /w_(\d+)/;
+const SRCSET_MIN_WIDTH_THRESHOLD = 400;
 const MEDIA_SRC_ATTRS = ["src", "poster"];
 const MEDIA_SRCSET_ATTRS = ["srcset"];
 const MEDIA_ELEMENTS = /* @__PURE__ */ new Set(["img", "video", "source"]);
@@ -80,6 +83,24 @@ const validate = (ctx) => {
         }
       }
     }
+    if (tagName === "img" && !el.getAttribute("srcset")) {
+      const srcValue = el.getAttribute("src");
+      if (srcValue) {
+        const srcParts = parseTemplateParts(srcValue);
+        const staticText = srcParts.filter((p) => p.kind === "static").map((p) => p.value).join("");
+        if (V1_TRANSFORM_RE.test(staticText)) {
+          const widthMatch = staticText.match(WIDTH_PARAM_RE);
+          if (widthMatch && parseInt(widthMatch[1], 10) >= SRCSET_MIN_WIDTH_THRESHOLD) {
+            findings.push({
+              severity: "warning",
+              message: "This image is ≥400px wide but has no srcset attribute. Add srcset with sizes for common breakpoints to serve appropriately sized images across devices. See agent-kit/wix-media.md for the responsive image pattern.",
+              element: "<img>",
+              attribute: "src"
+            });
+          }
+        }
+      }
+    }
     for (const attr of MEDIA_SRCSET_ATTRS) {
       const value = el.getAttribute(attr);
       if (!value) continue;
@@ -100,7 +121,7 @@ const validate = (ctx) => {
   });
   return findings;
 };
-function formatDimensions(file) {
+function formatDimensions$1(file) {
   if (file.width && file.height) {
     return `${file.width}x${file.height}`;
   }
@@ -120,12 +141,134 @@ function generateMediaIndex(files2) {
   lines.push("| ------ | ---- | ------------ | ---- | ---------- | ------ | --- |");
   for (const file of files2) {
     lines.push(
-      `| ${escapeMarkdownCell(file.folderName)} | ${file.slug} | ${escapeMarkdownCell(file.displayName)} | ${file.mediaType} | ${formatDimensions(file)} | ${formatLabels(file.labels)} | ${file.url} |`
+      `| ${escapeMarkdownCell(file.folderName)} | ${file.slug} | ${escapeMarkdownCell(file.displayName)} | ${file.mediaType} | ${formatDimensions$1(file)} | ${formatLabels(file.labels)} | ${file.url} |`
     );
   }
   lines.push("");
   return lines.join("\n");
 }
+const CATEGORY = "Media";
+function subCategoryForMediaType(mediaType) {
+  switch (mediaType.toLowerCase()) {
+    case "image":
+      return "Images";
+    case "video":
+      return "Videos";
+    case "audio":
+      return "Audio";
+    case "document":
+      return "Documents";
+    default:
+      return "Other";
+  }
+}
+function uniqueItemId(slug, mediaId, usedIds) {
+  const base = slug.trim() || mediaId.slice(0, 8);
+  let id = `wix-media:${base}`;
+  let suffix = 2;
+  while (usedIds.has(id)) {
+    id = `wix-media:${base}-${suffix++}`;
+  }
+  usedIds.add(id);
+  return id;
+}
+function formatDimensions(file) {
+  if (file.width && file.height) {
+    return `${file.width}×${file.height}`;
+  }
+  return "-";
+}
+function formatTitle(file) {
+  const folder = file.folderName?.trim();
+  if (folder && folder !== "Media Root" && folder !== "Unknown") {
+    return `${folder} — ${file.displayName}`;
+  }
+  return file.displayName;
+}
+const VISUAL_FILE_EXTENSION_RE = /\.(svg|png|jpe?g|gif|webp|bmp|ico)($|[?#])/i;
+function hasVisualFileExtension(file) {
+  return VISUAL_FILE_EXTENSION_RE.test(`${file.displayName} ${file.url}`);
+}
+function isPreviewableVisualMedia(file) {
+  const type = file.mediaType.toLowerCase();
+  if (type === "image" || type === "vector") return true;
+  return hasVisualFileExtension(file);
+}
+function thumbnailUrlForMedia(file) {
+  const url = file.url.trim();
+  if (!url || !isPreviewableVisualMedia(file)) return void 0;
+  return url;
+}
+function stagePlaceInteractionForMedia(file) {
+  const mediaType = file.mediaType.toLowerCase();
+  if (mediaType === "image" || mediaType === "vector" || isPreviewableVisualMedia(file)) {
+    return {
+      mode: "stage-place",
+      persistOnPage: true,
+      stagePromptTemplate: `Place this image at the marker location on the page.
+URL: ${file.url}`
+    };
+  }
+  if (mediaType === "video") {
+    return {
+      mode: "stage-place",
+      persistOnPage: true,
+      stagePromptTemplate: `Place this video at the marker location on the page.
+URL: ${file.url}`
+    };
+  }
+  return void 0;
+}
+function buildMediaPrompt(file) {
+  const labels = file.labels.length > 0 ? `Labels: ${file.labels.join(", ")}
+` : "";
+  const folderLine = file.folderName && file.folderName !== "Unknown" ? `Folder: ${file.folderName}
+` : "";
+  return [
+    "Use this Wix Media Manager asset in jay-html (do not copy to public/):",
+    `URL: ${file.url}`,
+    `Media id: ${file.id}`,
+    `Slug: ${file.slug}`,
+    `Type: ${file.mediaType} · ${formatDimensions(file)}`,
+    folderLine.trimEnd(),
+    labels.trimEnd(),
+    "Full media index: agent-kit/references/wix-media/MEDIA-INDEX.md",
+    "See agent-kit/designer/wix-media.md for fit/fill/crop transforms."
+  ].filter((line) => line.length > 0).join("\n");
+}
+function buildMediaAddMenuItems(files2) {
+  const usedIds = /* @__PURE__ */ new Set();
+  return files2.map((file) => {
+    const thumbnail = thumbnailUrlForMedia(file);
+    const interaction = stagePlaceInteractionForMedia(file);
+    return {
+      id: uniqueItemId(file.slug, file.id, usedIds),
+      title: formatTitle(file),
+      category: CATEGORY,
+      subCategory: subCategoryForMediaType(file.mediaType),
+      pluginName: "wix-media",
+      packageName: "@jay-framework/wix-media",
+      ...thumbnail ? { thumbnail } : {},
+      ...interaction ? { interaction } : {},
+      prompt: buildMediaPrompt(file)
+    };
+  });
+}
+const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/wix-media.generated.yaml";
+function writeGeneratedAddMenuCatalog(projectRoot, items) {
+  const outputPath = path.join(projectRoot, ADD_MENU_GENERATED_REL);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const header = "# DO NOT EDIT BY HAND — regenerated by wix-media (setup / rebuild-index)\n\n";
+  const body = yaml.dump({ items }, { indent: 2, lineWidth: 120, noRefs: true });
+  fs.writeFileSync(outputPath, header + body, "utf-8");
+  return ADD_MENU_GENERATED_REL;
+}
+async function refreshMediaAddMenuCatalog(projectRoot, mediaService) {
+  const files2 = await mediaService.listPublicFiles();
+  const items = buildMediaAddMenuItems(files2);
+  const outputRel = writeGeneratedAddMenuCatalog(projectRoot, items);
+  return { itemCount: items.length, outputRel };
+}
 const WIX_MEDIA_SERVICE_MARKER = createJayService("Wix Media Service");
 let filesClientInstance;
 let foldersClientInstance;
@@ -288,9 +431,14 @@ async function generateWixMediaReferences(ctx) {
   const mediaIndexContent = generateMediaIndex(mediaFiles);
   const mediaIndexPath = path.join(ctx.referencesDir, "MEDIA-INDEX.md");
   fs.writeFileSync(mediaIndexPath, mediaIndexContent, "utf-8");
+  const addMenuItems = buildMediaAddMenuItems(mediaFiles);
+  const addMenuGenerated = writeGeneratedAddMenuCatalog(ctx.projectRoot, addMenuItems);
   return {
-    referencesCreated: [`agent-kit/references/${ctx.pluginName}/MEDIA-INDEX.md`],
-    message: `${mediaFiles.length} media files indexed.`
+    referencesCreated: [
+      `agent-kit/references/${ctx.pluginName}/MEDIA-INDEX.md`,
+      addMenuGenerated
+    ],
+    message: `${mediaFiles.length} media files indexed; ${addMenuItems.length} Add Menu items.`
   };
 }
 const rebuildIndex = makeCliCommand("rebuild-index").withServices(CONSOLE_CONTEXT).withHandler(async (input, console) => {
@@ -309,8 +457,13 @@ const rebuildIndex = makeCliCommand("rebuild-index").withServices(CONSOLE_CONTEX
   const indexContent = generateMediaIndex(files2);
   const indexPath = path$1.join(referencesDir, "MEDIA-INDEX.md");
   fs$1.writeFileSync(indexPath, indexContent, "utf-8");
+  const addMenuPath = writeGeneratedAddMenuCatalog(
+    console.projectRoot,
+    buildMediaAddMenuItems(files2)
+  );
   console.log(`Media index written to ${indexPath}`);
-  return { success: true };
+  console.log(`Add Menu catalog written to ${addMenuPath}`);
+  return { success: true, fileCount: files2.length, addMenuPath };
 });
 const UPLOAD_INDEX_FILE = ".wix-media-uploads.json";
 const MEDIA_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -450,10 +603,15 @@ const uploadPublic = makeCliCommand("upload-public").withServices(CONSOLE_CONTEX
   return { success: failed === 0 };
 });
 export {
+  ADD_MENU_GENERATED_REL,
+  buildMediaAddMenuItems,
   generateMediaIndex,
   generateWixMediaReferences,
   rebuildIndex,
+  refreshMediaAddMenuCatalog,
   setupWixMedia,
+  thumbnailUrlForMedia,
   uploadPublic,
-  validate
+  validate,
+  writeGeneratedAddMenuCatalog
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-media",
-  "version": "0.19.6",
+  "version": "0.20.0",
   "type": "module",
   "description": "Wix Media Manager plugin for Jay Framework — media validation, index generation, and agent-kit references",
   "license": "Apache-2.0",
@@ -25,19 +25,20 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.19.6",
-    "@jay-framework/compiler-shared": "^0.19.6",
-    "@jay-framework/component": "^0.19.6",
-    "@jay-framework/fullstack-component": "^0.19.6",
-    "@jay-framework/stack-server-runtime": "^0.19.6",
-    "@jay-framework/wix-server-client": "^0.19.6",
-    "@jay-framework/wix-utils": "^0.19.6",
+    "@jay-framework/compiler-jay-html": "^0.20.0",
+    "@jay-framework/compiler-shared": "^0.20.0",
+    "@jay-framework/component": "^0.20.0",
+    "@jay-framework/fullstack-component": "^0.20.0",
+    "@jay-framework/stack-server-runtime": "^0.20.0",
+    "@jay-framework/wix-server-client": "^0.20.0",
+    "@jay-framework/wix-utils": "^0.20.0",
     "@wix/media": "^1.0.247",
-    "@wix/sdk": "^1.21.5"
+    "@wix/sdk": "^1.21.5",
+    "js-yaml": "^4.1.0"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.19.6",
-    "@jay-framework/vite-plugin": "^0.19.6",
+    "@jay-framework/compiler-jay-stack": "^0.20.0",
+    "@jay-framework/vite-plugin": "^0.20.0",
     "@types/node": "^20.11.0",
     "node-html-parser": "^6.1.0",
     "rimraf": "^5.0.5",