@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.2

package/dist/lib/v2/projection/creative-delivery.js

@@ -36,6 +36,7 @@ var import_jcs = require('../../utils/jcs.js');
 var import_catalog = require('./catalog.js');
 var import_resolve_agent_properties = require('../../discovery/resolve-agent-properties.js');
 var import_address_guards = require('../../net/address-guards.js');
+var import_legacy_metadata2 = require('./legacy-metadata.js');
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -531,16 +532,38 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
-function legacyRefParameterConstraints(ref) {
+function primaryMediaConstraints(creative) {
+  const assetType = creative.format_kind === "image" ? "image" : creative.format_kind === "video_hosted" ? "video" : creative.format_kind === "audio_hosted" ? "audio" : void 0;
+  if (!assetType) return void 0;
+  const assets = Object.values(record(creative.assets) ?? {}).flatMap(
+    (value) => (Array.isArray(value) ? value : [value]).flatMap((item) => {
+      const asset2 = record(item);
+      return asset2?.asset_type === assetType ? [asset2] : [];
+    })
+  );
+  if (assets.length !== 1) return void 0;
+  const asset = assets[0];
+  const width = assetType === "audio" ? void 0 : positiveConstraint(asset.width);
+  const height = assetType === "audio" ? void 0 : positiveConstraint(asset.height);
+  const durationMs = assetType === "image" ? void 0 : positiveConstraint(asset.duration_ms);
+  return width === void 0 && height === void 0 && durationMs === void 0 ? void 0 : { width, height, durationMs };
+}
+function positiveConstraint(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function legacyRefParameterConstraints(ref, selectorParams) {
   const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record((0, import_v1_to_v2.canonicalDeclarationFromBareId)(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  const selector = record(selectorParams);
+  const sizes = Array.isArray(selector?.sizes) ? selector.sizes : [];
+  const size = sizes.length === 1 ? record(sizes[0]) : void 0;
   return {
-    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
-    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
-    durationMs: ref.duration_ms
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : positiveConstraint(selector?.width) ?? positiveConstraint(size?.width),
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : positiveConstraint(selector?.height) ?? positiveConstraint(size?.height),
+    durationMs: ref.duration_ms ?? positiveConstraint(selector?.duration_ms_exact) ?? positiveConstraint(selector?.duration_ms)
   };
 }
-function refContradictsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refContradictsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
     return true;
   }
@@ -552,8 +575,8 @@ function refContradictsConstraints(ref, constraints) {
   }
   return false;
 }
-function refPinsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refPinsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
   if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
   if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
@@ -565,8 +588,8 @@ function legacyIdPinsDimensions(ref) {
   const params = record(declaration.params) ?? {};
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
-function refConstraintKey(ref) {
-  const constraints = legacyRefParameterConstraints(ref);
+function refConstraintKey(ref, selectorParams) {
+  const constraints = legacyRefParameterConstraints(ref, selectorParams);
   return [
     agentIdentity(ref.agent_url),
     constraints.width ?? "",
@@ -593,6 +616,7 @@ function candidateDeliveryTypes(candidate) {
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
   let remaining = candidates;
+  const mediaKind = ["image", "video_hosted", "audio_hosted"].includes(String(creative.format_kind));
   const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
   if (deliveryTypes) {
     remaining = remaining.filter((candidate) => {
@@ -604,17 +628,25 @@ function preferMostConstrainedLegacyCandidates(candidates, creative) {
     const supportedSizes = assetRenderedSizes(creative);
     if (supportedSizes.length > 1)
       remaining = remaining.filter(
-        (candidate) => supportedSizes.some((size) => !refContradictsConstraints(candidate.ref, size))
+        (candidate) => supportedSizes.some(
+          (size) => !refContradictsConstraints(candidate.ref, size, mediaKind ? candidate.selectorParams : void 0)
+        )
       );
   }
-  const constraints = creativeFormatParameterConstraints(creative);
+  const constraints = creativeFormatParameterConstraints(creative) ?? (remaining.length > 1 ? primaryMediaConstraints(creative) : void 0);
   if (constraints) {
-    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
+    remaining = remaining.filter(
+      (candidate) => !refContradictsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
+    const pinned = remaining.filter(
+      (candidate) => refPinsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
     if (pinned.length > 0) remaining = pinned;
   }
   if (remaining.length <= 1) return remaining;
-  const constraintKeys = new Set(remaining.map((candidate) => refConstraintKey(candidate.ref)));
+  const constraintKeys = new Set(
+    remaining.map((candidate) => refConstraintKey(candidate.ref, mediaKind ? candidate.selectorParams : void 0))
+  );
   if (constraintKeys.size !== 1) return remaining;
   const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
   return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
@@ -653,43 +685,82 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
+function legacyUrlTrackerSlotMatches(slot, tracker) {
+  return slot.asset_type === "url" && slot.requirements?.url_type === "tracker_pixel" && (slot.asset_id === tracker.assetId || slot.requirements.role === tracker.assetId);
+}
 function projectLegacyAssetKeys(assetsValue, definition) {
+  const unchanged = { assets: assetsValue, drifts: [] };
   const assets = record(assetsValue);
-  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  if (!assets || !Array.isArray(definition?.assets)) return unchanged;
   const slots = definition.assets.filter((slot) => record(slot) !== void 0);
-  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return unchanged;
   const declaredIds = new Set(slots.map((slot) => slot.asset_id));
   const availableSlots = slots.filter(
-    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+    (slot) => typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
   );
   const targetBySource = /* @__PURE__ */ new Map();
   const sourcesByTarget = /* @__PURE__ */ new Map();
+  const trackersBySource = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(assets)) {
-    if (declaredIds.has(key)) continue;
+    const candidates = (Array.isArray(value) ? value : [value]).map(import_legacy_metadata2.downgradePixelTracker);
+    const trackers = candidates.length > 0 && candidates.every((tracker) => tracker !== void 0) ? candidates : void 0;
+    const trackerSlotMatches = (slot2) => trackers !== void 0 && trackers.every((tracker) => legacyUrlTrackerSlotMatches(slot2, tracker));
+    if (declaredIds.has(key)) {
+      const slot2 = slots.find((slot3) => slot3.asset_id === key);
+      if (trackers && slot2 && trackerSlotMatches(slot2)) trackersBySource.set(key, trackers);
+      continue;
+    }
     const asset = record(value);
-    if (!asset || typeof asset.asset_type !== "string") continue;
-    const matches = availableSlots.filter((slot) => {
-      if (slot.asset_type !== asset.asset_type) return false;
+    if (!trackers && (!asset || typeof asset.asset_type !== "string")) continue;
+    const matches = availableSlots.filter((slot2) => {
+      if (trackerSlotMatches(slot2)) return true;
+      if (!asset || slot2.asset_type !== asset.asset_type) return false;
       if (asset.asset_type === "url") {
-        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+        return typeof asset.url_type === "string" && asset.url_type === slot2.requirements?.url_type;
       }
       if (asset.asset_type === "pixel_tracker") {
-        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+        return typeof asset.event === "string" && asset.event === slot2.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot2.custom_event_name);
       }
       return true;
     });
     if (matches.length !== 1) continue;
-    const target = matches[0].asset_id;
+    const slot = matches[0];
+    const target = slot.asset_id;
     targetBySource.set(key, target);
+    if (trackers && trackerSlotMatches(slot)) trackersBySource.set(key, trackers);
     const sources = sourcesByTarget.get(target) ?? [];
     sources.push(key);
     sourcesByTarget.set(target, sources);
   }
   for (const sources of sourcesByTarget.values()) {
-    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+    if (sources.length > 1) {
+      for (const source of sources) {
+        targetBySource.delete(source);
+        trackersBySource.delete(source);
+      }
+    }
   }
-  if (targetBySource.size === 0) return assetsValue;
-  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+  if (targetBySource.size === 0 && trackersBySource.size === 0) return unchanged;
+  const drifts = [];
+  for (const [key, trackers] of trackersBySource) {
+    trackers.forEach((tracker, index) => {
+      const path = `assets.${key}${Array.isArray(assets[key]) ? `[${index}]` : ""}`;
+      const drift = (0, import_legacy_metadata2.pixelTrackerDrift)(path, tracker);
+      if (drift) drifts.push(drift);
+    });
+  }
+  return {
+    assets: Object.fromEntries(
+      Object.entries(assets).map(([key, value]) => {
+        const trackers = trackersBySource.get(key);
+        return [
+          targetBySource.get(key) ?? key,
+          trackers ? Array.isArray(value) ? trackers.map((tracker) => tracker.asset) : trackers[0].asset : value
+        ];
+      })
+    ),
+    drifts
+  };
 }
 function renderedSizeFields(asset) {
   if (asset.width !== void 0 || asset.height !== void 0)
@@ -725,7 +796,6 @@ function projectInlineMarkupToLegacyHtml(assetsValue, definition, operation, cre
         {
           asset_type: "html",
           content: asset.markup,
-          ...renderedSizeFields(asset),
           ...asset.provenance !== void 0 && { provenance: asset.provenance }
         }
       ];
@@ -787,15 +857,34 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
     }
   }
   if (Object.hasOwn(creative, "assets")) {
-    next.assets = projectLegacyAssetKeys(
-      projectInlineMarkupToLegacyHtml(
-        creative.assets,
-        markupDefinition,
-        operation,
-        typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
-      ),
-      definition
+    const legacyAssets = projectInlineMarkupToLegacyHtml(
+      creative.assets,
+      markupDefinition,
+      operation,
+      typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
     );
+    const refSize = legacyRefParameterConstraints(formatId);
+    const acceptsDimensions = Array.isArray(markupDefinition?.accepts_parameters) && markupDefinition.accepts_parameters.includes("dimensions");
+    const hasFixedRender = Array.isArray(markupDefinition?.renders) && markupDefinition.renders.some(
+      (render) => typeof render.dimensions?.width === "number" || typeof render.dimensions?.height === "number"
+    );
+    if (legacyAssets !== creative.assets && acceptsDimensions && !hasFixedRender && refSize.width === void 0 && refSize.height === void 0) {
+      const inlineAssets = Object.fromEntries(
+        Object.entries(record(creative.assets) ?? {}).filter(([, value]) => {
+          const asset = record(value);
+          return asset?.asset_type === "display_tag" && asset.delivery_type === "inline_markup";
+        })
+      );
+      const size = assetRenderedSize({ assets: inlineAssets });
+      const requested = creativeFormatParameterConstraints(creative);
+      if (typeof size?.width === "number" && typeof size.height === "number" && Number.isSafeInteger(size.width) && Number.isSafeInteger(size.height) && size.width > 0 && size.height > 0 && (requested?.width === void 0 || requested.width === size.width) && (requested?.height === void 0 || requested.height === size.height)) {
+        next.format_id = { ...formatId, width: size.width, height: size.height };
+      }
+    }
+    const projected = projectLegacyAssetKeys(legacyAssets, definition);
+    next.assets = projected.assets;
+    (0, import_legacy_metadata.transferLegacyCreativeMetadata)(creative, next);
+    (0, import_legacy_metadata2.rememberCreativeDeliveryDiagnostics)(next, projected.drifts);
   }
   return next;
 }
@@ -1051,6 +1140,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
     legacyFormatConverter,
     wireMode === "canonical"
   );
+  (0, import_legacy_metadata.transferLegacyCreativeMetadata)(inputRecord, creativeRecord);
   if (wireMode === "canonical") return creativeRecord;
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -1130,14 +1220,44 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    const htmlMarkupHint = kind === "html5" && offered.includes("display_tag") ? ". HTML-markup formats (display_html, display_WxH_html) take display_tag inline markup since SDK 17; send HTML snippets as a display_tag asset with delivery_type inline_markup (docs/migration-16-to-17.md)" : "";
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}${htmlMarkupHint}`;
+  }
+  const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
+  if (deliveryTypes) {
+    const accepting = sameKind.filter((candidate) => {
+      const accepted = candidateDeliveryTypes(candidate);
+      return [...deliveryTypes].every((type) => accepted.includes(type));
+    });
+    if (accepting.length === 0) {
+      const accepted = [...new Set(sameKind.flatMap((candidate) => candidateDeliveryTypes(candidate).map(String)))];
+      return `none of the seller's ${sameKind.length} ${kind} legacy refs accepts delivery_type ${[...deliveryTypes].join(", ")} (they accept ${accepted.join(", ")})`;
+    }
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

package/dist/lib/v2/projection/creative-delivery.mjs

@@ -15,6 +15,11 @@ import { canonicalize as canonicalizeJson } from "../../utils/jcs.mjs";
 import { lookupUniqueV1FormatById, lookupV1Format } from "./catalog.mjs";
 import { canonicalizeAgentUrl } from "../../discovery/resolve-agent-properties.mjs";
 import { isLikelyPrivateUrl } from "../../net/address-guards.mjs";
+import {
+  downgradePixelTracker,
+  pixelTrackerDrift,
+  rememberCreativeDeliveryDiagnostics
+} from "./legacy-metadata.mjs";
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -510,16 +515,38 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
-function legacyRefParameterConstraints(ref) {
+function primaryMediaConstraints(creative) {
+  const assetType = creative.format_kind === "image" ? "image" : creative.format_kind === "video_hosted" ? "video" : creative.format_kind === "audio_hosted" ? "audio" : void 0;
+  if (!assetType) return void 0;
+  const assets = Object.values(record(creative.assets) ?? {}).flatMap(
+    (value) => (Array.isArray(value) ? value : [value]).flatMap((item) => {
+      const asset2 = record(item);
+      return asset2?.asset_type === assetType ? [asset2] : [];
+    })
+  );
+  if (assets.length !== 1) return void 0;
+  const asset = assets[0];
+  const width = assetType === "audio" ? void 0 : positiveConstraint(asset.width);
+  const height = assetType === "audio" ? void 0 : positiveConstraint(asset.height);
+  const durationMs = assetType === "image" ? void 0 : positiveConstraint(asset.duration_ms);
+  return width === void 0 && height === void 0 && durationMs === void 0 ? void 0 : { width, height, durationMs };
+}
+function positiveConstraint(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function legacyRefParameterConstraints(ref, selectorParams) {
   const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record(canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  const selector = record(selectorParams);
+  const sizes = Array.isArray(selector?.sizes) ? selector.sizes : [];
+  const size = sizes.length === 1 ? record(sizes[0]) : void 0;
   return {
-    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
-    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
-    durationMs: ref.duration_ms
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : positiveConstraint(selector?.width) ?? positiveConstraint(size?.width),
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : positiveConstraint(selector?.height) ?? positiveConstraint(size?.height),
+    durationMs: ref.duration_ms ?? positiveConstraint(selector?.duration_ms_exact) ?? positiveConstraint(selector?.duration_ms)
   };
 }
-function refContradictsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refContradictsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
     return true;
   }
@@ -531,8 +558,8 @@ function refContradictsConstraints(ref, constraints) {
   }
   return false;
 }
-function refPinsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refPinsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
   if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
   if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
@@ -544,8 +571,8 @@ function legacyIdPinsDimensions(ref) {
   const params = record(declaration.params) ?? {};
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
-function refConstraintKey(ref) {
-  const constraints = legacyRefParameterConstraints(ref);
+function refConstraintKey(ref, selectorParams) {
+  const constraints = legacyRefParameterConstraints(ref, selectorParams);
   return [
     agentIdentity(ref.agent_url),
     constraints.width ?? "",
@@ -572,6 +599,7 @@ function candidateDeliveryTypes(candidate) {
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
   let remaining = candidates;
+  const mediaKind = ["image", "video_hosted", "audio_hosted"].includes(String(creative.format_kind));
   const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
   if (deliveryTypes) {
     remaining = remaining.filter((candidate) => {
@@ -583,17 +611,25 @@ function preferMostConstrainedLegacyCandidates(candidates, creative) {
     const supportedSizes = assetRenderedSizes(creative);
     if (supportedSizes.length > 1)
       remaining = remaining.filter(
-        (candidate) => supportedSizes.some((size) => !refContradictsConstraints(candidate.ref, size))
+        (candidate) => supportedSizes.some(
+          (size) => !refContradictsConstraints(candidate.ref, size, mediaKind ? candidate.selectorParams : void 0)
+        )
       );
   }
-  const constraints = creativeFormatParameterConstraints(creative);
+  const constraints = creativeFormatParameterConstraints(creative) ?? (remaining.length > 1 ? primaryMediaConstraints(creative) : void 0);
   if (constraints) {
-    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
+    remaining = remaining.filter(
+      (candidate) => !refContradictsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
+    const pinned = remaining.filter(
+      (candidate) => refPinsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
     if (pinned.length > 0) remaining = pinned;
   }
   if (remaining.length <= 1) return remaining;
-  const constraintKeys = new Set(remaining.map((candidate) => refConstraintKey(candidate.ref)));
+  const constraintKeys = new Set(
+    remaining.map((candidate) => refConstraintKey(candidate.ref, mediaKind ? candidate.selectorParams : void 0))
+  );
   if (constraintKeys.size !== 1) return remaining;
   const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
   return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
@@ -632,43 +668,82 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
+function legacyUrlTrackerSlotMatches(slot, tracker) {
+  return slot.asset_type === "url" && slot.requirements?.url_type === "tracker_pixel" && (slot.asset_id === tracker.assetId || slot.requirements.role === tracker.assetId);
+}
 function projectLegacyAssetKeys(assetsValue, definition) {
+  const unchanged = { assets: assetsValue, drifts: [] };
   const assets = record(assetsValue);
-  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  if (!assets || !Array.isArray(definition?.assets)) return unchanged;
   const slots = definition.assets.filter((slot) => record(slot) !== void 0);
-  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return unchanged;
   const declaredIds = new Set(slots.map((slot) => slot.asset_id));
   const availableSlots = slots.filter(
-    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+    (slot) => typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
   );
   const targetBySource = /* @__PURE__ */ new Map();
   const sourcesByTarget = /* @__PURE__ */ new Map();
+  const trackersBySource = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(assets)) {
-    if (declaredIds.has(key)) continue;
+    const candidates = (Array.isArray(value) ? value : [value]).map(downgradePixelTracker);
+    const trackers = candidates.length > 0 && candidates.every((tracker) => tracker !== void 0) ? candidates : void 0;
+    const trackerSlotMatches = (slot2) => trackers !== void 0 && trackers.every((tracker) => legacyUrlTrackerSlotMatches(slot2, tracker));
+    if (declaredIds.has(key)) {
+      const slot2 = slots.find((slot3) => slot3.asset_id === key);
+      if (trackers && slot2 && trackerSlotMatches(slot2)) trackersBySource.set(key, trackers);
+      continue;
+    }
     const asset = record(value);
-    if (!asset || typeof asset.asset_type !== "string") continue;
-    const matches = availableSlots.filter((slot) => {
-      if (slot.asset_type !== asset.asset_type) return false;
+    if (!trackers && (!asset || typeof asset.asset_type !== "string")) continue;
+    const matches = availableSlots.filter((slot2) => {
+      if (trackerSlotMatches(slot2)) return true;
+      if (!asset || slot2.asset_type !== asset.asset_type) return false;
       if (asset.asset_type === "url") {
-        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+        return typeof asset.url_type === "string" && asset.url_type === slot2.requirements?.url_type;
       }
       if (asset.asset_type === "pixel_tracker") {
-        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+        return typeof asset.event === "string" && asset.event === slot2.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot2.custom_event_name);
       }
       return true;
     });
     if (matches.length !== 1) continue;
-    const target = matches[0].asset_id;
+    const slot = matches[0];
+    const target = slot.asset_id;
     targetBySource.set(key, target);
+    if (trackers && trackerSlotMatches(slot)) trackersBySource.set(key, trackers);
     const sources = sourcesByTarget.get(target) ?? [];
     sources.push(key);
     sourcesByTarget.set(target, sources);
   }
   for (const sources of sourcesByTarget.values()) {
-    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+    if (sources.length > 1) {
+      for (const source of sources) {
+        targetBySource.delete(source);
+        trackersBySource.delete(source);
+      }
+    }
   }
-  if (targetBySource.size === 0) return assetsValue;
-  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+  if (targetBySource.size === 0 && trackersBySource.size === 0) return unchanged;
+  const drifts = [];
+  for (const [key, trackers] of trackersBySource) {
+    trackers.forEach((tracker, index) => {
+      const path = `assets.${key}${Array.isArray(assets[key]) ? `[${index}]` : ""}`;
+      const drift = pixelTrackerDrift(path, tracker);
+      if (drift) drifts.push(drift);
+    });
+  }
+  return {
+    assets: Object.fromEntries(
+      Object.entries(assets).map(([key, value]) => {
+        const trackers = trackersBySource.get(key);
+        return [
+          targetBySource.get(key) ?? key,
+          trackers ? Array.isArray(value) ? trackers.map((tracker) => tracker.asset) : trackers[0].asset : value
+        ];
+      })
+    ),
+    drifts
+  };
 }
 function renderedSizeFields(asset) {
   if (asset.width !== void 0 || asset.height !== void 0)
@@ -704,7 +779,6 @@ function projectInlineMarkupToLegacyHtml(assetsValue, definition, operation, cre
         {
           asset_type: "html",
           content: asset.markup,
-          ...renderedSizeFields(asset),
           ...asset.provenance !== void 0 && { provenance: asset.provenance }
         }
       ];
@@ -766,15 +840,34 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
     }
   }
   if (Object.hasOwn(creative, "assets")) {
-    next.assets = projectLegacyAssetKeys(
-      projectInlineMarkupToLegacyHtml(
-        creative.assets,
-        markupDefinition,
-        operation,
-        typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
-      ),
-      definition
+    const legacyAssets = projectInlineMarkupToLegacyHtml(
+      creative.assets,
+      markupDefinition,
+      operation,
+      typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
+    );
+    const refSize = legacyRefParameterConstraints(formatId);
+    const acceptsDimensions = Array.isArray(markupDefinition?.accepts_parameters) && markupDefinition.accepts_parameters.includes("dimensions");
+    const hasFixedRender = Array.isArray(markupDefinition?.renders) && markupDefinition.renders.some(
+      (render) => typeof render.dimensions?.width === "number" || typeof render.dimensions?.height === "number"
     );
+    if (legacyAssets !== creative.assets && acceptsDimensions && !hasFixedRender && refSize.width === void 0 && refSize.height === void 0) {
+      const inlineAssets = Object.fromEntries(
+        Object.entries(record(creative.assets) ?? {}).filter(([, value]) => {
+          const asset = record(value);
+          return asset?.asset_type === "display_tag" && asset.delivery_type === "inline_markup";
+        })
+      );
+      const size = assetRenderedSize({ assets: inlineAssets });
+      const requested = creativeFormatParameterConstraints(creative);
+      if (typeof size?.width === "number" && typeof size.height === "number" && Number.isSafeInteger(size.width) && Number.isSafeInteger(size.height) && size.width > 0 && size.height > 0 && (requested?.width === void 0 || requested.width === size.width) && (requested?.height === void 0 || requested.height === size.height)) {
+        next.format_id = { ...formatId, width: size.width, height: size.height };
+      }
+    }
+    const projected = projectLegacyAssetKeys(legacyAssets, definition);
+    next.assets = projected.assets;
+    transferLegacyCreativeMetadata(creative, next);
+    rememberCreativeDeliveryDiagnostics(next, projected.drifts);
   }
   return next;
 }
@@ -1030,6 +1123,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
     legacyFormatConverter,
     wireMode === "canonical"
   );
+  transferLegacyCreativeMetadata(inputRecord, creativeRecord);
   if (wireMode === "canonical") return creativeRecord;
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -1109,14 +1203,44 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    const htmlMarkupHint = kind === "html5" && offered.includes("display_tag") ? ". HTML-markup formats (display_html, display_WxH_html) take display_tag inline markup since SDK 17; send HTML snippets as a display_tag asset with delivery_type inline_markup (docs/migration-16-to-17.md)" : "";
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}${htmlMarkupHint}`;
+  }
+  const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
+  if (deliveryTypes) {
+    const accepting = sameKind.filter((candidate) => {
+      const accepted = candidateDeliveryTypes(candidate);
+      return [...deliveryTypes].every((type) => accepted.includes(type));
+    });
+    if (accepting.length === 0) {
+      const accepted = [...new Set(sameKind.flatMap((candidate) => candidateDeliveryTypes(candidate).map(String)))];
+      return `none of the seller's ${sameKind.length} ${kind} legacy refs accepts delivery_type ${[...deliveryTypes].join(", ")} (they accept ${accepted.join(", ")})`;
+    }
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

package/dist/lib/v2/projection/index.d.mts

@@ -47,6 +47,7 @@ export { canonicalFormatLegacyResolverFromRoutes, carryFormatOptionOrigins, lega
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response.mjs';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders.mjs';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side.mjs';
+export { getCreativeDeliveryDiagnostics } from './legacy-metadata.mjs';
 export type { V1FormatId, V2ProductFormatDeclaration, V2ProductInput, V2Product, V1ProductInput, V1Product, ProjectionProductInput, ProjectionDiagnostic, } from './types.mjs';
 export { isProjectionProductInput } from './types.mjs';
 export { legacyFormatConverterFromCatalogSnapshots, canonicalFormatLegacyResolverFromCatalogSnapshots, projectionAdaptersFromCatalogSnapshots, type ProjectionCatalogAdapters, type ProjectionCatalogSnapshot, type ProjectionCatalogSource, } from './catalog-snapshot.mjs';