@wix/himalaya-cli 0.1201.0 → 0.1203.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/dev-server/src/builder.d.ts

@@ -610,6 +610,8 @@ export declare function formField(props: {
  * opens the device photo picker; the renderer uploads the bytes to Wix Media and
  * calls `<uploadService>.genUpload`/`setMedia` on the screen's worker so the well
  * previews the photo and the worker can attach it on save. Generic (any app).
+ * Declared in core.proto as `media_field = 163` (#3744); `label` also names the
+ * well for assistive technology, so pass one.
  */
 export declare function mediaField(props: {
     valuePath: string;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/schema.d.ts

@@ -1549,6 +1549,22 @@ export interface RichContentEditorProps {
     /** Rendered when the engine page is unavailable (not bundled / missing / failed / 15 s timeout). */
     fallback?: Component;
 }
+/**
+ * #3744 — an image well bound to a `$service:` image URL. Tapping it opens the platform photo
+ * picker (PhotosPicker on iOS, the Android photo picker, a file chooser on web); the renderer
+ * then runs the upload contract against the screen's worker: `<uploadService>.genUpload({fileName,
+ * mimeType})` → PUT the bytes to `<uploadService>.uploadUrl` + `?filename=<fileName>` →
+ * `<uploadService>.setMedia({mediaId, imageUrl})`. The well previews whatever `valuePath`
+ * resolves to, so the worker updating that value in `setMedia` is what shows the new photo.
+ */
+export interface MediaFieldProps {
+    /** `$service:<svc>.<path>` → the current image URL; empty ⇒ the empty well with `label`. */
+    valuePath: string;
+    /** The worker service exposing `genUpload` / `setMedia` and the `uploadUrl` value. */
+    uploadService: string;
+    /** Empty-well copy (a message key or literal). Default "Add a photo". */
+    label?: string;
+}
 /**
  * RFC 0063 — a Wix Ricos rich-content document rendered natively: headings, lists, links,
  * images, galleries, video, tables and link cards (never a WebView). The document travels as a
@@ -2379,6 +2395,10 @@ export type CoreComponentBody = {
     package: "himalaya";
     type: "RichContentEditor";
     props: RichContentEditorProps;
+} | {
+    package: "himalaya";
+    type: "MediaField";
+    props: MediaFieldProps;
 } | {
     package: "himalaya";
     type: "VoiceNote";

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/core/validation.mjs

@@ -193,7 +193,7 @@ function errorMessageFor(args) {
   if (worker) return worker;
   const failure = validate(args.rule, args.value);
   if (!failure) return null;
-  if (args.rule?.message) return args.rule.message;
+  if (typeof args.rule?.message === "string" && args.rule.message.trim()) return args.rule.message;
   return defaultMessage(failure, args.catalog);
 }
 function shouldRevealError(args) {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/core.mjs

@@ -8774,6 +8774,8 @@ var CORE_COMPONENTS = /* @__PURE__ */ new Set([
   "himalaya.RichContent",
   // Rich content editor — RFC 0063 §6
   "himalaya.RichContentEditor",
+  // Image well + Wix Media upload — #3744
+  "himalaya.MediaField",
   // Recorded-audio bubble — messenger design G4
   "himalaya.VoiceNote",
   "himalaya.Marquee",
@@ -9251,7 +9253,7 @@ function errorMessageFor(args) {
   if (worker) return worker;
   const failure = validate(args.rule, args.value);
   if (!failure) return null;
-  if (args.rule?.message) return args.rule.message;
+  if (typeof args.rule?.message === "string" && args.rule.message.trim()) return args.rule.message;
   return defaultMessage(failure, args.catalog);
 }
 function shouldRevealError(args) {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/state.mjs

@@ -155,7 +155,7 @@ function errorMessageFor(args) {
   if (worker) return worker;
   const failure = validate(args.rule, args.value);
   if (!failure) return null;
-  if (args.rule?.message) return args.rule.message;
+  if (typeof args.rule?.message === "string" && args.rule.message.trim()) return args.rule.message;
   return defaultMessage(failure, args.catalog);
 }
 var nonEmpty = (type) => (v) => typeof v === "string" && v.length > 0 && isValid({ type }, v);

package/dist/cli.mjs

@@ -6818,6 +6818,7 @@ function walk(node, registry, path2, out2) {
 var SYSTEM_FONT_FAMILY, TONAL_ELEVATION_ALPHA, COLOR_TOKEN_PROPS, TYPOGRAPHY_TOKEN_PROPS;
 var init_tokens = __esm({
   "../../core/ts/src/tokens.ts"() {
+    "use strict";
     SYSTEM_FONT_FAMILY = "$system";
     TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
     COLOR_TOKEN_PROPS = {
@@ -6868,6 +6869,7 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s) => s !== "t").join("|")})\\b|^\\$t:`
@@ -7825,6 +7827,8 @@ var init_validator = __esm({
       "himalaya.RichContent",
       // Rich content editor — RFC 0063 §6
       "himalaya.RichContentEditor",
+      // Image well + Wix Media upload — #3744
+      "himalaya.MediaField",
       // Recorded-audio bubble — messenger design G4
       "himalaya.VoiceNote",
       "himalaya.Marquee",
@@ -8265,6 +8269,9 @@ var init_a11y_contract = __esm({
       VoiceNote: { role: "group", name: "required", state: ["playing", "duration/position"], decorative: false },
       Map: { role: "image", name: "required", state: [], decorative: false },
       WebView: { role: "group", name: "required", state: [], decorative: false },
+      // #3744 — the image well is a BUTTON (it opens the photo picker), named by its `label` on every
+      // renderer — including once a photo fills the well and the label is no longer drawn.
+      MediaField: { role: "button", name: "required", state: ["photo set / empty", "uploading"], decorative: false },
       // ---- Interactive controls -----------------------------------------------------------
       Button: { role: "button", name: "required", state: ["disabled"], decorative: false },
       Fab: { role: "button", name: "required", state: ["disabled"], decorative: false },
@@ -10359,6 +10366,33 @@ function richContentEditorFindings(descriptor) {
   visit(descriptor, "", true, false);
   return out2;
 }
+function mediaFieldFindings(descriptor) {
+  const out2 = [];
+  const visit = (v, path2, atRoot) => {
+    if (Array.isArray(v)) {
+      v.forEach((x, i) => visit(x, `${path2}[${i}]`, false));
+      return;
+    }
+    if (!v || typeof v !== "object") return;
+    const record2 = v;
+    const body = record2.body;
+    if (body?.package === "himalaya" && body.type === "MediaField") {
+      const p = body.props ?? {};
+      if (typeof p.valuePath !== "string" || !p.valuePath.startsWith("$service:") || !WHOLE_VALUE_BINDING.test(p.valuePath)) {
+        out2.push({ path: path2, message: `MediaField.valuePath must be a "$service:<service>.<field>" binding to the current image URL, got ${JSON.stringify(p.valuePath ?? null)} \u2014 every renderer reads it only as a binding to one field, so the well would stay empty` });
+      }
+      if (typeof p.uploadService !== "string" || !EDITOR_SERVICE_NAME.test(p.uploadService)) {
+        out2.push({ path: path2, message: `MediaField.uploadService must name a worker service (letters, digits, "_" or "-") exposing genUpload / setMedia, got ${JSON.stringify(p.uploadService ?? null)}` });
+      }
+    }
+    for (const [key2, child] of Object.entries(record2)) {
+      if (isOpaqueAuthorJson(key2, child, atRoot)) continue;
+      visit(child, path2 ? `${path2}.${key2}` : key2, false);
+    }
+  };
+  visit(descriptor, "", true);
+  return out2;
+}
 function renderedWixMediaReferences(descriptor) {
   const record2 = descriptor && typeof descriptor === "object" ? descriptor : null;
   const regions = record2 && "payload" in record2 ? [
@@ -10468,6 +10502,9 @@ function validateScreenDescriptor(screenId, descriptor, opts = {}) {
   for (const finding of richContentEditorFindings(descriptor)) {
     issues.push({ severity: "error", pass: "rich-content-editor", path: finding.path, message: finding.message });
   }
+  for (const finding of mediaFieldFindings(descriptor)) {
+    issues.push({ severity: "error", pass: "media-field", path: finding.path, message: finding.message });
+  }
   const bindings = collectServiceBindings(descriptor);
   const descriptorActions = collectDescriptorActions(descriptor);
   const workerActions = descriptorActions.filter(({ actionId }) => actionId.startsWith("tier5."));
@@ -11316,6 +11353,7 @@ var init_validate_descriptor_core = __esm({
         zoom: "number"
       },
       Marquee: { color: "string", durationMs: "number", style: "string", text: "string" },
+      MediaField: { label: "string", uploadService: "string", valuePath: "string" },
       MediaPlayer: {
         allowCellular: "boolean",
         appearance: "any",
@@ -11691,6 +11729,7 @@ var init_validate_descriptor_core = __esm({
       Form: ["id", "submitButton"],
       FragmentSlot: ["casePath", "defaultCase"],
       Icon: ["name"],
+      MediaField: ["valuePath", "uploadService"],
       ProgressBar: ["progress"],
       SegmentedControl: ["selectedId"],
       Snackbar: ["message"],
@@ -25205,7 +25244,7 @@ function errorMessageFor(args) {
   if (worker) return worker;
   const failure = validate(args.rule, args.value);
   if (!failure) return null;
-  if (args.rule?.message) return args.rule.message;
+  if (typeof args.rule?.message === "string" && args.rule.message.trim()) return args.rule.message;
   return defaultMessage(failure, args.catalog);
 }
 function shouldRevealError(args) {
@@ -32628,6 +32667,181 @@ var init_richContentEditor = __esm({
   }
 });
 
+// ../../core/web-host/src/actions/presigned-upload-policy.ts
+function hostMatches(host) {
+  const h = host.toLowerCase().split(":")[0];
+  return PRESIGNED_UPLOAD_HOST_ROOTS.some((r) => h === r || h.endsWith(`.${r}`));
+}
+function isPresignedUploadTarget(raw) {
+  if (!raw) return false;
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== "https:") return false;
+  if (u.username || u.password) return false;
+  return hostMatches(u.hostname);
+}
+var PRESIGNED_UPLOAD_HOST_ROOTS, MAX_INLINE_BASE64_BYTES, MAX_UPLOAD_BYTES;
+var init_presigned_upload_policy = __esm({
+  "../../core/web-host/src/actions/presigned-upload-policy.ts"() {
+    PRESIGNED_UPLOAD_HOST_ROOTS = ["wixmp.com"];
+    MAX_INLINE_BASE64_BYTES = 8 * 1024 * 1024;
+    MAX_UPLOAD_BYTES = 32 * 1024 * 1024;
+  }
+});
+
+// ../../core/web-renderer/src/mediaFieldUpload.ts
+function mediaFieldName(label2) {
+  return typeof label2 === "string" && label2.trim() !== "" ? label2 : MEDIA_FIELD_DEFAULT_LABEL;
+}
+function mediaFieldState(uploading, hasPhoto, failed2 = false) {
+  if (uploading) return "Uploading";
+  if (failed2) return MEDIA_FIELD_UPLOAD_FAILED;
+  return hasPhoto ? "Photo added" : void 0;
+}
+function mediaFieldServicePath(valuePath) {
+  if (typeof valuePath !== "string" || !valuePath.startsWith("$service:")) return null;
+  const p = valuePath.slice("$service:".length);
+  return p === "" ? null : p;
+}
+function mediaFieldFileName(sizeBytes, mimeType) {
+  const ext = /png/i.test(mimeType) ? "png" : /gif/i.test(mimeType) ? "gif" : /webp/i.test(mimeType) ? "webp" : /hei[cf]/i.test(mimeType) ? "heic" : "jpg";
+  return `photo-${Math.max(0, Math.floor(sizeBytes))}.${ext}`;
+}
+function isMediaFieldUploadTarget(url) {
+  return typeof url === "string" && isPresignedUploadTarget(url);
+}
+async function runMediaFieldUpload(o) {
+  const { uploadService: svc, file, deps } = o;
+  if (!svc) return { ok: false, reason: "no_service" };
+  const t = deps.timers ?? { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: (h) => clearTimeout(h) };
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  let expired = false;
+  let onExpire = [];
+  const timer = t.setTimeout(() => {
+    expired = true;
+    controller?.abort();
+    for (const fn of onExpire) fn();
+    onExpire = [];
+  }, o.timeoutMs ?? MEDIA_FIELD_UPLOAD_TIMEOUT_MS);
+  const bounded2 = (p) => {
+    if (expired) return Promise.reject(new Deadline());
+    return new Promise((resolve57, reject) => {
+      const stop = () => reject(new Deadline());
+      onExpire.push(stop);
+      p.then(resolve57, reject).finally(() => {
+        onExpire = onExpire.filter((f) => f !== stop);
+      });
+    });
+  };
+  const dispatchedAs = async (action) => {
+    try {
+      const r = deps.dispatch(action);
+      if (r && typeof r.then === "function") {
+        const v = await bounded2(Promise.resolve(r));
+        return v === null ? "rejected" : "settled";
+      }
+      return "unknown";
+    } catch {
+      return "rejected";
+    }
+  };
+  const dispatched = async (action) => await dispatchedAs(action) !== "rejected";
+  try {
+    const urlPath = `${svc}.uploadUrl`;
+    const before = deps.value(urlPath);
+    let uploadUrl;
+    try {
+      uploadUrl = await bounded2(new Promise((resolve57, reject) => {
+        let done = false;
+        let unsub = () => {
+        };
+        unsub = deps.subscribe(urlPath, (v) => {
+          if (done || typeof v !== "string" || v === "" || v === before) return;
+          done = true;
+          queueMicrotask(() => unsub());
+          resolve57(v);
+        });
+        onExpire.push(() => {
+          if (!done) {
+            done = true;
+            queueMicrotask(() => unsub());
+          }
+        });
+        void dispatchedAs({ actionId: `tier5.${svc}.genUpload`, args: { fileName: file.fileName, mimeType: file.mimeType } }).then((how) => {
+          if (done || how === "unknown") return;
+          if (how === "settled") {
+            const now = deps.value(urlPath);
+            if (typeof now === "string" && now !== "" && now !== before) {
+              done = true;
+              queueMicrotask(() => unsub());
+              resolve57(now);
+              return;
+            }
+          }
+          done = true;
+          queueMicrotask(() => unsub());
+          reject(new ActionRejected());
+        });
+      }));
+    } catch (e) {
+      return { ok: false, reason: e instanceof ActionRejected ? "gen_upload" : "timeout" };
+    }
+    if (!isMediaFieldUploadTarget(uploadUrl)) return { ok: false, reason: "bad_target" };
+    let body;
+    try {
+      body = await bounded2(Promise.resolve(typeof file.body === "function" ? file.body() : file.body));
+    } catch (e) {
+      return { ok: false, reason: e instanceof Deadline ? "timeout" : "read" };
+    }
+    const sep19 = uploadUrl.includes("?") ? "&" : "?";
+    let res;
+    try {
+      res = await bounded2(deps.fetch(`${uploadUrl}${sep19}filename=${encodeURIComponent(file.fileName)}`, {
+        method: "PUT",
+        headers: { "Content-Type": file.mimeType },
+        body,
+        ...controller ? { signal: controller.signal } : {}
+      }));
+    } catch (e) {
+      return { ok: false, reason: e instanceof Deadline || expired ? "timeout" : "put" };
+    }
+    if (!res.ok) return { ok: false, reason: "put" };
+    let json6;
+    try {
+      json6 = await bounded2(res.json());
+    } catch (e) {
+      return { ok: false, reason: e instanceof Deadline || expired ? "timeout" : "bad_descriptor" };
+    }
+    const root = json6 && typeof json6 === "object" ? json6 : {};
+    const d = root.file && typeof root.file === "object" ? root.file : root;
+    const mediaId = typeof d.id === "string" ? d.id : "";
+    if (!mediaId) return { ok: false, reason: "bad_descriptor" };
+    const imageUrl = typeof d.url === "string" ? d.url : "";
+    if (!await dispatched({ actionId: `tier5.${svc}.setMedia`, args: { mediaId, imageUrl } })) return { ok: false, reason: "set_media" };
+    return { ok: true, mediaId, imageUrl };
+  } finally {
+    t.clearTimeout(timer);
+    onExpire = [];
+  }
+}
+var MEDIA_FIELD_DEFAULT_LABEL, MEDIA_FIELD_UPLOAD_TIMEOUT_MS, MEDIA_FIELD_UPLOAD_FAILED, Deadline, ActionRejected;
+var init_mediaFieldUpload = __esm({
+  "../../core/web-renderer/src/mediaFieldUpload.ts"() {
+    init_presigned_upload_policy();
+    MEDIA_FIELD_DEFAULT_LABEL = "Add a photo";
+    MEDIA_FIELD_UPLOAD_TIMEOUT_MS = 3e4;
+    MEDIA_FIELD_UPLOAD_FAILED = "Upload failed";
+    Deadline = class extends Error {
+    };
+    ActionRejected = class extends Error {
+    };
+  }
+});
+
 // ../../core/web-renderer/src/pdfSource.ts
 function pdfEmbedPlan(url, pageOrigin = currentOrigin()) {
   const target = classifyEmbedUrl(url, pageOrigin);
@@ -35832,9 +36046,10 @@ function renderInner(node, ctx) {
       return /* @__PURE__ */ jsx8(IconNode, { props, ctx, wrap });
     case "Button":
       return /* @__PURE__ */ jsx8(ButtonNode, { props, ctx, wrap });
+    case "MediaField":
+      return /* @__PURE__ */ jsx8(MediaFieldNode, { props, ctx, wrap });
     case "TextField":
     case "RichTextField":
-    case "MediaField":
       return /* @__PURE__ */ jsx8(EditableField, { props, ctx, wrap, multiline: type === "RichTextField" });
     case "Toggle":
       return /* @__PURE__ */ jsx8(ToggleNode, { props, ctx, wrap });
@@ -36214,7 +36429,7 @@ function renderInner(node, ctx) {
     }
   }
 }
-var useIsomorphicLayoutEffect, ResponsiveGrid, SPLIT_EXPANDED_MIN_WIDTH, SPLIT_COLUMN_GAP, ResponsiveSplitView, ABSOLUTE_URL_RE, appearKeyframesInjected, pressStylesInjected, FOCUS_RING_CSS, focusStylesInjected, HLIST_CHILD_CSS, hListStylesInjected, listAnimateRuntimeInstalled, transitionKeyframesInjected, countUpRuntimeInjected, MEASURE_PREFIX, measureRuntimeInjected, revealRuntimeInjected, vectorAnimStylesInjected, scrollProgressRuntimeInjected, confettiRuntimeInjected, lottieRuntimeInjected, riveRuntimeInjected, gradientKeyframesInjected, parallaxRuntimeInjected, spinKeyframesInjected, marqueeKeyframesInjected, alignItems, zJustifyItems, hAlignItems, bodyFont, kids2, rowKidCtx, rowKids, staggeredKids, asTextL10n, asBoundText, useBoundString, InterpolatedTextView, txt, selectFragmentCase, fragmentValueHash, fragmentSlotContent, FragmentSlotNode, RichContentEditorNode, WorkerSubtreeNode, RichContentNode, resolveItemDeep2, resolveSwipeActions, resolveModBindings, resolvedComponentId, directServiceBindings, withRootStyle, ReactiveDirectScalars, HiddenGate, KEYBOARD_INPUT_MODES, AUTOCAPITALIZE_VALUES, ENTER_KEY_HINTS, AUTOGROW_CEILING, EditableField, MenuNode, LoadMoreSentinel, FieldErrorNode, FormView, MediaSlotProvider, MEDIA_ITEM_BINDABLE, MediaPlayerView, VideoNode, PdfViewNode, WebViewNode, InteractivePicker, InteractiveDatePicker, InteractiveSearchField, InteractiveStepper, SYNTHETIC_TAP_ROLE, SYNTHETIC_TABINDEX, INFERRED_DECORATIVE, SELF_RENDERED_LEAF, ROLE_WHEN_NAMED, AUTHORED_ROLE, PENDING_RANGE, RANGE_ROLES, NODE_A11Y_ATTRS, INTERACTIVE_ROLES, ALWAYS_INTERACTIVE_COMPONENT_TYPES, controlNode, ToggleNode, SliderNode, SelectionControlNode, TabsNode, SegmentedControlNode, DisclosureGroupNode, GridNode, SplitViewNode, TextNode, ImageNode, ANIMATION_LEAF, LottieNode, RiveNode, AvatarNode, IconNode, ButtonNode, OtpInputNode, ProgressBarNode, ACTIVITY_DEFAULT_NAME, ActivityIndicatorNode, NATIVELY_TABBABLE, BottomSheetNode, PRESENTED_OVERLAY_ATTR, PopoverNode, ChipsInputNode, ChipNode, TableNode, GaugeRing, GaugeNode, RATING_METRICS, ratingMetrics, RatingNode, AvatarStripNode, CHART_STROKE_CYCLE, chartStrokeAt, chartBarCenter, ChartNode, donutSliceOpacity, DonutChartNode, LegendMarker, LegendNode, cellAlign, DataTableNode, voiceNoteState, voiceNoteDelivery, VOICE_NOTE_DEFAULT_BARS, clampBarCount, VoiceNoteNode, TimelineNode, WheelPickerNode, ColorPickerNode, FilterChipsNode, TILE_PX, MAX_MERCATOR_LAT, DEFAULT_TILE_MAX_ZOOM, CIRCLE_SEGMENTS, METRES_PER_DEG_LAT, MARKER_HIT_RADIUS, SHAPE_HIT_RADIUS, MapNode, CollapsingHeaderNode, UnsupportedOnSurface, CALENDAR_DATE_ONLY_RE, CAL_DEFAULT_MAX_DOTS, CAL_AGENDA_INITIAL_DAYS, CAL_AGENDA_PAGE_DAYS, CAL_DEFAULT_SNAP_MINUTES, CAL_UNASSIGNED_LANE_ID, MonthCalendarNode, TimeGridNode, AgendaNode, ARIA_ROLE, initialFocusScheduled, PRESENTED_SCOPE, focusRoots, A11yHintDescription, WebRenderer;
+var useIsomorphicLayoutEffect, ResponsiveGrid, SPLIT_EXPANDED_MIN_WIDTH, SPLIT_COLUMN_GAP, ResponsiveSplitView, ABSOLUTE_URL_RE, appearKeyframesInjected, pressStylesInjected, FOCUS_RING_CSS, focusStylesInjected, HLIST_CHILD_CSS, hListStylesInjected, listAnimateRuntimeInstalled, transitionKeyframesInjected, countUpRuntimeInjected, MEASURE_PREFIX, measureRuntimeInjected, revealRuntimeInjected, vectorAnimStylesInjected, scrollProgressRuntimeInjected, confettiRuntimeInjected, lottieRuntimeInjected, riveRuntimeInjected, gradientKeyframesInjected, parallaxRuntimeInjected, spinKeyframesInjected, marqueeKeyframesInjected, alignItems, zJustifyItems, hAlignItems, bodyFont, kids2, rowKidCtx, rowKids, staggeredKids, asTextL10n, asFinalTextL10n, asBoundText, useBoundString, InterpolatedTextView, txt, selectFragmentCase, fragmentValueHash, fragmentSlotContent, FragmentSlotNode, RichContentEditorNode, MediaFieldNode, WorkerSubtreeNode, RichContentNode, resolveItemDeep2, resolveSwipeActions, resolveModBindings, resolvedComponentId, directServiceBindings, withRootStyle, ReactiveDirectScalars, HiddenGate, KEYBOARD_INPUT_MODES, AUTOCAPITALIZE_VALUES, ENTER_KEY_HINTS, AUTOGROW_CEILING, EditableField, MenuNode, LoadMoreSentinel, FieldErrorNode, FormView, MediaSlotProvider, MEDIA_ITEM_BINDABLE, MediaPlayerView, VideoNode, PdfViewNode, WebViewNode, InteractivePicker, InteractiveDatePicker, InteractiveSearchField, InteractiveStepper, SYNTHETIC_TAP_ROLE, SYNTHETIC_TABINDEX, INFERRED_DECORATIVE, SELF_RENDERED_LEAF, ROLE_WHEN_NAMED, AUTHORED_ROLE, PENDING_RANGE, RANGE_ROLES, NODE_A11Y_ATTRS, INTERACTIVE_ROLES, ALWAYS_INTERACTIVE_COMPONENT_TYPES, controlNode, ToggleNode, SliderNode, SelectionControlNode, TabsNode, SegmentedControlNode, DisclosureGroupNode, GridNode, SplitViewNode, TextNode, ImageNode, ANIMATION_LEAF, LottieNode, RiveNode, AvatarNode, IconNode, ButtonNode, OtpInputNode, ProgressBarNode, ACTIVITY_DEFAULT_NAME, ActivityIndicatorNode, NATIVELY_TABBABLE, BottomSheetNode, PRESENTED_OVERLAY_ATTR, PopoverNode, ChipsInputNode, ChipNode, TableNode, GaugeRing, GaugeNode, RATING_METRICS, ratingMetrics, RatingNode, AvatarStripNode, CHART_STROKE_CYCLE, chartStrokeAt, chartBarCenter, ChartNode, donutSliceOpacity, DonutChartNode, LegendMarker, LegendNode, cellAlign, DataTableNode, voiceNoteState, voiceNoteDelivery, VOICE_NOTE_DEFAULT_BARS, clampBarCount, VoiceNoteNode, TimelineNode, WheelPickerNode, ColorPickerNode, FilterChipsNode, TILE_PX, MAX_MERCATOR_LAT, DEFAULT_TILE_MAX_ZOOM, CIRCLE_SEGMENTS, METRES_PER_DEG_LAT, MARKER_HIT_RADIUS, SHAPE_HIT_RADIUS, MapNode, CollapsingHeaderNode, UnsupportedOnSurface, CALENDAR_DATE_ONLY_RE, CAL_DEFAULT_MAX_DOTS, CAL_AGENDA_INITIAL_DAYS, CAL_AGENDA_PAGE_DAYS, CAL_DEFAULT_SNAP_MINUTES, CAL_UNASSIGNED_LANE_ID, MonthCalendarNode, TimeGridNode, AgendaNode, ARIA_ROLE, initialFocusScheduled, PRESENTED_SCOPE, focusRoots, A11yHintDescription, WebRenderer;
 var init_renderNode = __esm({
   "../../core/web-renderer/src/renderNode.tsx"() {
     "use strict";
@@ -36233,6 +36448,7 @@ var init_renderNode = __esm({
     init_icons();
     init_webviewFrame();
     init_richContentEditor();
+    init_mediaFieldUpload();
     init_pdfSource();
     init_icon_catalog_generated();
     init_controls();
@@ -36369,6 +36585,7 @@ var init_renderNode = __esm({
       return React7.cloneElement(el, { key: n?.id ?? i, style: { ...prev, animationDelay: `${i * staggerMs}ms` } });
     }) : null;
     asTextL10n = (v, ctx) => typeof v === "string" && v.startsWith(TRANSLATION_PREFIX) ? asText2(resolveTranslation(v, ctx.catalog)) : asText2(v);
+    asFinalTextL10n = (v, ctx) => typeof v === "string" ? v.startsWith(TRANSLATION_PREFIX) ? asText2(resolveTranslation(v, ctx.catalog)) : v : asText2(v);
     asBoundText = (v, ctx) => isBinding(v) ? asTextL10n(resolveScalarStatic(v, ctx) ?? "", ctx) : asText2(v);
     useBoundString = (v, ctx) => {
       const resolved2 = useResolvedScalar(v, ctx);
@@ -36471,6 +36688,78 @@ var init_renderNode = __esm({
       return fragmentSlotContent({ props, ctx, discriminator, slotId: nodeId, extra: wrap });
     });
     RichContentEditorNode = withExtras("RichContentEditorNode", ({ props, ctx, wrap, nodeId }) => /* @__PURE__ */ jsx8(RichContentEditorView, { props, ctx, wrap, nodeId, renderChild: (n) => renderNode(n, ctx) }));
+    MediaFieldNode = withExtras("MediaFieldNode", ({ props, ctx, wrap }) => {
+      const C = ctx.color;
+      const servicePathStr = mediaFieldServicePath(props.valuePath);
+      const bound = useBoundValue(ctx, servicePathStr ? String(props.valuePath) : "");
+      const imageUrl = typeof bound === "string" ? bound : "";
+      const [uploading, setUploading] = React7.useState(false);
+      const [failed2, setFailed] = React7.useState(false);
+      const fileRef = React7.useRef(null);
+      const uploadService = typeof props.uploadService === "string" ? props.uploadService : "";
+      const resolvedLabel = asText2(resolveScalarStatic(props.label, ctx));
+      const name = mediaFieldName(resolvedLabel);
+      const state = mediaFieldState(uploading, imageUrl !== "", failed2);
+      const open = () => {
+        if (!uploading) fileRef.current?.click();
+      };
+      const onPick = async (e) => {
+        const input = e.currentTarget;
+        const file = input.files?.[0];
+        input.value = "";
+        if (!file || !ctx.onAction || !ctx.provider || !uploadService) return;
+        const provider = ctx.provider;
+        const mimeType = file.type || "image/jpeg";
+        setUploading(true);
+        setFailed(false);
+        try {
+          const r = await runMediaFieldUpload({
+            uploadService,
+            file: { mimeType, fileName: mediaFieldFileName(file.size, mimeType), body: file },
+            deps: {
+              dispatch: (action) => ctx.onAction?.(action),
+              value: (p) => provider.value(p),
+              subscribe: (p, cb) => provider.subscribe(p, cb),
+              fetch: (url, init) => fetch(url, init)
+            }
+          });
+          if (!r.ok) setFailed(true);
+        } catch {
+          setFailed(true);
+        } finally {
+          setUploading(false);
+        }
+      };
+      const f = ctx.font("bodyEmphasis");
+      const radius = 12;
+      return /* @__PURE__ */ jsxs5(
+        "div",
+        {
+          role: "button",
+          tabIndex: 0,
+          "aria-label": state ? `${name}, ${state}` : name,
+          "aria-busy": uploading || void 0,
+          "data-media-service": uploadService,
+          onClick: open,
+          onKeyDown: (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              open();
+            }
+          },
+          style: { position: "relative", display: "flex", alignItems: "center", justifyContent: "center", width: "100%", height: 160, borderRadius: radius, overflow: "hidden", background: C("surfaceSecondary", "#F2F3F5"), cursor: "pointer", boxSizing: "border-box", ...wrap },
+          children: [
+            /* @__PURE__ */ jsx8("input", { ref: fileRef, type: "file", accept: "image/*", tabIndex: -1, "aria-hidden": "true", onChange: onPick, onClick: (e) => e.stopPropagation(), style: { display: "none" } }),
+            imageUrl ? /* @__PURE__ */ jsx8("img", { src: resolveAssetUrl(imageUrl, ctx.assetBaseUrl), alt: "", "aria-hidden": "true", style: { position: "absolute", inset: 0, width: "100%", height: "100%", objectFit: "cover", display: "block" } }) : /* @__PURE__ */ jsxs5("div", { "aria-hidden": "true", style: { display: "flex", flexDirection: "column", alignItems: "center", gap: 8, color: accentTextColor(ctx) }, children: [
+              iconSvg("camera", { size: 28, color: accentTextColor(ctx) }),
+              /* @__PURE__ */ jsx8("span", { style: { fontFamily: fontStack(f.family, ctx.idiom), fontWeight: f.weight, fontSize: f.remSize }, children: name })
+            ] }),
+            uploading ? /* @__PURE__ */ jsx8("div", { "aria-hidden": "true", "data-media-uploading": "true", style: { position: "absolute", inset: 0, background: "rgba(0,0,0,0.35)" } }) : null,
+            failed2 && !uploading ? /* @__PURE__ */ jsx8("span", { "aria-hidden": "true", "data-media-upload-error": "true", style: { position: "absolute", left: 8, right: 8, bottom: 8, textAlign: "center", fontSize: pxToRem(13), color: C("danger", "#E62214") }, children: MEDIA_FIELD_UPLOAD_FAILED }) : null
+          ]
+        }
+      );
+    });
     WorkerSubtreeNode = withExtras("WorkerSubtreeNode", ({ props, ctx, wrap, nodeId }) => {
       const slotId = nodeId;
       const extra = wrap;
@@ -36690,12 +36979,20 @@ var init_renderNode = __esm({
         () => ctx.catalog ? new Proxy({}, { get: (_t, k) => typeof k === "string" ? ctx.catalog.get(k) : void 0 }) : void 0,
         [ctx.catalog]
       );
-      const rawMessage = errorMessageFor({ rule, value: local, workerError, catalog: validationCatalog });
-      const resolvedMessage = useBoundString(rawMessage ?? "", ctx);
-      const message = rawMessage === null || !resolvedMessage.trim() ? null : resolvedMessage;
+      const translateOnly = (v) => asFinalTextL10n(v, ctx);
+      const ruleMessageRaw = typeof rule?.message === "string" || rule?.message !== null && typeof rule?.message === "object" ? rule?.message : void 0;
+      const ruleMessageBound = typeof ruleMessageRaw === "string" && isBinding(ruleMessageRaw) && !ruleMessageRaw.startsWith(TRANSLATION_PREFIX);
+      const ruleMessageResolved = useResolvedScalar(ruleMessageBound ? ruleMessageRaw : void 0, ctx);
+      const ruleMessageText = ruleMessageRaw == null ? "" : ruleMessageBound ? ruleMessageResolved == null ? "" : translateOnly(ruleMessageResolved) : translateOnly(ruleMessageRaw);
+      const ruleMessagePending = ruleMessageBound && !ruleMessageText.trim() && ruleMessageRaw.startsWith("$service:") && !!ctx.provider && !(formBag?.submitAttempted ?? false);
+      const effectiveRule = !rule || ruleMessageRaw == null ? rule : { ...rule, message: ruleMessageText };
+      const rawMessage = errorMessageFor({ rule: effectiveRule, value: local, workerError, catalog: validationCatalog });
+      const hasWorkerError = Boolean(workerError && workerError.trim());
+      const painted2 = rawMessage === null ? "" : translateOnly(rawMessage);
+      const message = !painted2.trim() || ruleMessagePending && !hasWorkerError ? null : painted2;
       const revealed = message !== null && shouldRevealError({
         rule,
-        hasWorkerError: Boolean(workerError && workerError.trim()),
+        hasWorkerError,
         touched,
         focused: isFocused,
         submitAttempted: formBag?.submitAttempted ?? false
@@ -40401,6 +40698,10 @@ function buildRenderTree(node, path2 = "$", provider = null, itemScope = void 0,
       }
     }
     if (type === "OtpInput" && props.secure === true) delete values.value;
+    if (type === "MediaField" && typeof props.valuePath === "string" && props.valuePath.startsWith("$service:")) {
+      const photo = resolveTreeScalar(props.valuePath, provider, itemScope);
+      if (typeof photo === "string" && photo !== "") delete values.label;
+    }
     collectComponentMediaValues(type, props, { provider, itemScope, values, insideMediaProperty: false });
     collectResolvedMediaValues(modifiers, "modifiers", {
       provider,
@@ -56151,8 +56452,8 @@ function allowed(url, declared) {
     if (declaredPort !== void 0 && (!/^\d+$/.test(declaredPort) || Number(declaredPort) > 65535)) return false;
     const defaultPort = url.protocol === "https:" ? "443" : "80";
     const portMatches = declaredPort !== void 0 ? String(Number(declaredPort)) === actualPort : actualPort === defaultPort;
-    const hostMatches = wildcard ? value !== normalized && value.endsWith(`.${normalized}`) : value === normalized || value.endsWith(`.${normalized}`);
-    return portMatches && hostMatches;
+    const hostMatches2 = wildcard ? value !== normalized && value.endsWith(`.${normalized}`) : value === normalized || value.endsWith(`.${normalized}`);
+    return portMatches && hostMatches2;
   });
 }
 function ipv4Private(address) {
@@ -61368,21 +61669,21 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-Bj2h2VLm.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1140295, sha256: "4501893b27a6121e14d79939efd53d5c88fd923cddab4314ecb5eb41de3233b9" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 1140303, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 1144913, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 1633497, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1724421, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1815405, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1906385, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1997257, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 2088237, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 2196873, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 2305957, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 2415005, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 2522705, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 2610813, length: 4947, sha256: "4bb31d3503d8874f0c8b90db2fafd58b0229ff64adeec94b2debf5ace8151c7a" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 2615760, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
+      { key: "assets/index-CPRJc_Hj.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1145737, sha256: "5e9c570a5baa2ef39ccf2d357c78631a2d5f9190acfb01dcc77ccce17538457a" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 1145745, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 1150355, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 1638939, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1729863, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1820847, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1911827, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 2002699, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 2093679, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 2202315, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 2311399, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 2420447, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 2528147, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 2616255, length: 4947, sha256: "20678191da952eca3f3fb8fb8b137db4cbb11dc84d0a8e59146cb669c5aa26b9" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 2621202, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
     ];
   }
 });

package/guides/component-reference.json

@@ -2,7 +2,7 @@
   "_comment": "GENERATED by core/web-embed/authoring/gen-reference.mjs from core/ts/src/schema.ts — do not hand-edit. The schema is the source of truth; regenerate on schema changes.",
   "schemaSource": "core/ts/src/schema.ts",
   "bindingGrammar": "$service:<service>.<path> (worker state) · $item.<field> (list row) · $flag:<key> (feature flag) · $env:<key> (client environment — #1056). Bindings resolve in the text/value props marked 'binding-aware' below — INCLUDING Modifiers token refs — but only `background` and `border.color`, which are the two whose token a binding actually fills: a worker can drive per-item theming (e.g. a game board's per-square color), not just text. `shadow` is NOT binding-aware on any renderer, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref — so `shadow: { token: \"$item.x\" }` and `backgroundGradient: { token: \"$item.x\" }` keep the sentinel and silently lose the per-item styling. Colour slots split by LEVEL, not by component: inside modifiers a colour is a TokenRef OBJECT ({ token: \"…\" }), inside props it is a bare TokenName STRING — there is no modifiers.color or modifiers.tint (see the 'Token slots' section in component-reference.md). A few input props render the LITERAL and are NOT binding-aware — notably SearchField.placeholder and Chip.label; SearchField.value is live and binding-aware like other content props. Bindings also CANNOT target strict-enum fields (style, size, alignment, severity, presentation, contentMode, …) — those fail at render, not validation. $env: is client-resolved (no worker) and valid in modifiers.hiddenPath and FragmentSlot.casePath ONLY — keys reduceMotion/colorScheme/sizeClass/isRTL, e.g. hiddenPath:\"$env:reduceMotion\" or hiddenPath:\"$env:colorScheme==light\", casePath:\"$env:colorScheme\"; unknown key fails open (shown / defaultCase).",
-  "componentCount": 84,
+  "componentCount": 85,
   "notImplementedComponents": [
     "Text",
     "Carousel",
@@ -1057,6 +1057,15 @@
       ],
       "propsSource": "export interface RichContentEditorProps {\n  /** Form-bag key. Required inside a Form (validator). */\n  name?: string;\n  /** `$service:<svc>.<path>` → the document JSON string. Seeds ONCE (the first non-empty value). */\n  documentPath?: string;\n  /** Literal seed document JSON. At most one of documentPath / documentJson. */\n  documentJson?: string;\n  placeholder?: string;\n  /** Empty ⇒ all, minus \"image\" unless uploadService is set. \"image\" requires uploadService. */\n  tools?: RichContentEditorTool[];\n  /** Debounced ≥ 500 ms; args = { dirty: \"true\" } — never the document. */\n  onChange?: Action;\n  /** Worker service made by `ricosUploadService` (@himalaya/wix-rich-content-editor). Enables \"image\". */\n  uploadService?: string;\n  /** Take the remaining height of a bounded parent; else `minHeight`. */\n  fillAvailable?: boolean;\n  /** Default 240. */\n  minHeight?: number;\n  /** Rendered when the engine page is unavailable (not bundled / missing / failed / 15 s timeout). */\n  fallback?: Component;\n}"
     },
+    {
+      "name": "MediaField",
+      "category": "Image well + Wix Media upload (#3744)",
+      "propsType": "MediaFieldProps",
+      "bindings": [
+        "valuePath"
+      ],
+      "propsSource": "export interface MediaFieldProps {\n  /** `$service:<svc>.<path>` → the current image URL; empty ⇒ the empty well with `label`. */\n  valuePath: string;\n  /** The worker service exposing `genUpload` / `setMedia` and the `uploadUrl` value. */\n  uploadService: string;\n  /** Empty-well copy (a message key or literal). Default \"Add a photo\". */\n  label?: string;\n}"
+    },
     {
       "name": "VoiceNote",
       "category": "Recorded-audio bubble (messenger design G4)",

package/guides/component-reference.md

@@ -3,7 +3,7 @@
 > GENERATED from `core/ts/src/schema.ts` by `core/web-embed/authoring/gen-reference.mjs`.
 > The schema is the source of truth — regenerate on schema changes; do not hand-edit.
 
-**84 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
+**85 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
 Binding grammar: `$service:<service>.<path>` (worker state) · `$item.<field>` (list row template) · `$flag:<key>` (feature flag) · `$env:<key>` (client environment — #1056).
 Bindings resolve in the text/value props marked **binding-aware** below — **including two `Modifiers` token refs**, `background` and `border.color`, which are the only two whose token a binding actually fills: a worker can drive per-item **theming** (e.g. a game board's per-square color, `background: { token: "$item.bg" }`), not just text content. `shadow` and `backgroundGradient` are `TokenRef`s but are **not** binding-aware on any renderer — `shadow: { token: "$item.x" }` keeps the sentinel as a literal token name and silently loses the per-item styling, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref.
 `$env:` is **client-resolved** (no worker) and valid in `modifiers.hiddenPath` and `FragmentSlot.casePath` **only** — keys `reduceMotion` / `colorScheme` / `sizeClass` / `isRTL`, with an optional `==`/`!=` comparison (e.g. `hiddenPath: "$env:reduceMotion"`, `hiddenPath: "$env:colorScheme==light"`, `casePath: "$env:colorScheme"`). An unknown key fails open (shown / `defaultCase`).
@@ -94,6 +94,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `DataTable` | Analytics data-viz | `rowsPath`, `totalsPath` |
 | `RichContent` | Rich content | `documentJsonPath` |
 | `RichContentEditor` | Rich content editor | `documentPath` |
+| `MediaField` | Image well + Wix Media upload (#3744) | `valuePath` |
 | `VoiceNote` | Recorded-audio bubble (messenger design G4) | `waveformPath`, `durationMsPath`, `positionMsPath`, `statePath`, `deliveryPath`, `ratePath` |
 | `Marquee` | Recorded-audio bubble (messenger design G4) | — |
 | `Timeline` | Recorded-audio bubble (messenger design G4) | `entriesPath` |
@@ -116,7 +117,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 
 These props are accepted by the schema and pass validation, but the named platform's renderer never reads them — they silently do nothing (no warning, no log). Prefer a prop NOT listed here, or drive the behaviour from a worker.
 
-**Scope: 20 of 84 components, all of them web / android / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
+**Scope: 20 of 85 components, all of them web / android / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
 
 - **`category` (7: `Menu`, `Tooltip`, `Popover`, `ChipsInput`, `OtpInput`, `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
 - **`styling` (13: `Text`, `Carousel`, `CollapsingHeader`, `Banner`, `Snackbar`, `WebView`, `Slider`, `SelectionControl`, `ActivityIndicator`, `Map`, `Video`, `PdfView`, `Agenda`)** — the component itself **works**; only the listed prop is inert. `Slider` on iOS is a working slider whose `debounceMs` does not throttle — not a broken `Slider`. Use the component; just do not depend on that one prop.
@@ -1667,6 +1668,21 @@ export interface RichContentEditorProps {
 
 > ⚠️ **`onChange` on ios + android — DIVERGES:** renders `fallback` only — no editor exists yet, so nothing dispatches on_change. The editor has not reached these renderers yet, so they show the descriptor's `fallback`; the editor runs on the web and in React Native hosts that register its adapter.
 
+### Image well + Wix Media upload (#3744)
+
+#### MediaField
+
+```ts
+export interface MediaFieldProps {
+  /** `$service:<svc>.<path>` → the current image URL; empty ⇒ the empty well with `label`. */
+  valuePath: string;
+  /** The worker service exposing `genUpload` / `setMedia` and the `uploadUrl` value. */
+  uploadService: string;
+  /** Empty-well copy (a message key or literal). Default "Add a photo". */
+  label?: string;
+}
+```
+
 ### Recorded-audio bubble (messenger design G4)
 
 #### VoiceNote

package/guides/index.json

@@ -1,7 +1,7 @@
 {
   "_comment": "AUTO-GENERATED by tools/authoring-kit/bundle.mjs — DO NOT EDIT. Regenerate with: npm run authoring:gen",
   "schemaStamp": {
-    "componentCount": 84,
+    "componentCount": 85,
     "schemaSource": "core/ts/src/schema.ts"
   },
   "portalUrl": "https://apps.wix.com/_api/himi-serve/docs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1201.0",
+  "version": "0.1203.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "da789b2bd209029f397baa8fd5f1d53d0cd64549c3eb4006ffb204d0"
+  "falconPackageHash": "36a72891777611eef63e609aa328947ea7a30540e4e0f9e4bc5e90ae"
 }