@osimart/create-storefront 0.0.0-stage → 1.0.1

package/app/logic/sections/SlideshowSection.js

@@ -0,0 +1,118 @@
+import { A11y, Autoplay, EffectFade, Keyboard } from "swiper/modules";
+
+export default function useLogic({ props }) {
+  const { s, shellStyle, innerStyle, customClass } = useSectionShell(() => props.section);
+  const { tree, editing, u } = useContentTree(() => props.section, {
+    rootDefaults: { DIRECTION: "HORIZONTAL" },
+    index: () => props.index,
+  });
+  const { num, px, upper } = u;
+
+  const slides = computed(() => tree.value.children.filter((n) => n.slide));
+  const count = computed(() => slides.value.length);
+
+  const swiper = ref(null);
+  const current = ref(0);
+  function onSwiper(instance) {
+    swiper.value = instance;
+  }
+  function onSlideChange(instance) {
+    current.value = trueLoop.value ? instance.realIndex : instance.activeIndex;
+  }
+
+  const fade = computed(() => upper(s.value.TRANSITION, "SLIDE") === "FADE");
+  const loopSetting = computed(() => s.value.LOOP !== false);
+  // Builder editing: rewind (backward transition, no clones — clones would
+  // duplicate data-osi-block and confuse the overlay). Live storefront: real
+  // loop (forward-continuous, no backward jump).
+  const rewind = computed(() => loopSetting.value && editing.value);
+  const trueLoop = computed(() => loopSetting.value && !editing.value && count.value > 1);
+  const adapt = computed(() => upper(s.value.HEIGHT, "LARGE") === "ADAPT");
+
+  const go = (i) => swiper.value?.slideToLoop ? swiper.value.slideToLoop(i) : swiper.value?.slideTo(i);
+  const next = () => swiper.value?.slideNext();
+  const prev = () => swiper.value?.slidePrev();
+  const canPrev = computed(() => rewind.value || trueLoop.value || current.value > 0);
+  const canNext = computed(() => rewind.value || trueLoop.value || current.value < count.value - 1);
+
+  /* ---------------------------------------------------------------- autoplay */
+
+  const reducedMotion = ref(false);
+  onMounted(() => {
+    reducedMotion.value = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+  });
+
+  const autoplay = computed(() =>
+    s.value.AUTOPLAY && !editing.value && !reducedMotion.value && count.value > 1
+      ? {
+          delay: Math.max(1500, num(s.value.INTERVAL, 5000)),
+          disableOnInteraction: false,
+          pauseOnMouseEnter: s.value.PAUSE_ON_HOVER !== false,
+        }
+      : false
+  );
+
+  // Swiper reads `autoplay` once; follow later changes (a settings edit, the
+  // builder connecting, reduced motion detected after mount).
+  watch(autoplay, (value) => {
+    const instance = swiper.value;
+    if (!instance?.autoplay) return;
+    if (value) {
+      Object.assign(instance.params.autoplay, value);
+      instance.autoplay.start();
+    } else {
+      instance.autoplay.stop();
+    }
+  });
+
+  /* ------------------------------------------------ builder: show the edited */
+
+  const { selectedKey } = usePreviewOverlay();
+  watch(
+    () => selectedKey.value,
+    (key) => {
+      if (!key) return;
+      const byKey = new Map((props.section.blocks ?? []).map((b) => [b.key, b]));
+      let block = byKey.get(key);
+      for (let guard = 0; block && block.type !== "SLIDE" && guard < 20; guard++) {
+        block = byKey.get(block.parent_key);
+      }
+      if (!block) return;
+      const at = slides.value.findIndex((n) => n.key === (block.id ?? block.key));
+      if (at >= 0 && at !== current.value) go(at);
+    }
+  );
+
+  // Slides added / removed / reordered in the builder: let Swiper re-measure.
+  watch(
+    () => slides.value.map((n) => n.key).join(),
+    () => nextTick(() => swiper.value?.update())
+  );
+
+  /* ------------------------------------------------------------------ sizing */
+
+  const HEIGHTS = { SMALL: "320px", MEDIUM: "480px", LARGE: "640px", FULL: "100svh", ADAPT: "auto" };
+
+  const vars = computed(() => {
+    const v = s.value;
+    const mode = upper(v.HEIGHT, "LARGE");
+    const height = mode === "CUSTOM" ? px(num(v.HEIGHT_CUSTOM, 560)) : HEIGHTS[mode] ?? HEIGHTS.LARGE;
+    return {
+      "--ss-h": height,
+      "--ss-h-m": adapt.value ? "auto" : px(v.HEIGHT_MOBILE) ?? height,
+      ...(v.ARROW_BG_COLOR ? { "--ss-arrow-bg": v.ARROW_BG_COLOR } : {}),
+      ...(v.ARROW_COLOR ? { "--ss-arrow": v.ARROW_COLOR } : {}),
+      ...(v.ARROW_SIZE ? { "--ss-arrow-size": px(v.ARROW_SIZE) } : {}),
+      ...(v.DOT_COLOR ? { "--ss-dot": v.DOT_COLOR } : {}),
+      ...(v.DOT_ACTIVE_COLOR ? { "--ss-dot-active": v.DOT_ACTIVE_COLOR } : {}),
+    };
+  });
+
+  const showArrows = computed(() => s.value.SHOW_ARROWS !== false && count.value > 1);
+  const showDots = computed(() => s.value.SHOW_DOTS !== false && count.value > 1);
+  const dotStyle = computed(() => (upper(s.value.DOT_STYLE, "DOT") === "BAR" ? "bar" : "dot"));
+
+  const modules = [A11y, Autoplay, EffectFade, Keyboard];
+
+  return { s, shellStyle, innerStyle, customClass, tree, editing, u, num, px, upper, slides, count, swiper, current, onSwiper, onSlideChange, fade, loopSetting, rewind, trueLoop, adapt, go, next, prev, canPrev, canNext, reducedMotion, autoplay, selectedKey, HEIGHTS, vars, showArrows, showDots, dotStyle, modules };
+}

package/app/logic/sections/SpacerSection.js

@@ -0,0 +1,37 @@
+/**
+ * SPACER — vertical breathing room, optionally with a divider line.
+ *
+ * The only section that intentionally renders nothing but space, so it
+ * deliberately skips useSectionShell's padding: a spacer with 48px of default
+ * section padding on top of its own height is 156px of gap when the merchant
+ * asked for 60.
+ */
+
+
+export default function useLogic({ props }) {
+  const { s, scheme, customClass } = useSectionShell(() => props.section);
+
+  // Numeric settings fields sometimes arrive as strings (or "60px"), and 0
+  // is a legitimate value — so don't rely on `||` fallback, which treats
+  // both NaN and 0 as "missing".
+  function toNum(val, fallback) {
+    const n = typeof val === 'string' ? parseFloat(val) : Number(val);
+    return Number.isFinite(n) ? n : fallback;
+  }
+
+  // Boolean settings fields sometimes arrive as the strings "true"/"false",
+  // which are both truthy in JS — so `!!val` alone is unsafe.
+  function toBool(val) {
+    if (typeof val === 'string') return val.toLowerCase() === 'true' || val === '1';
+    return !!val;
+  }
+
+  const height = computed(() => toNum(s.value.SPACER_HEIGHT, 60));
+  const heightMobile = computed(() =>
+    toNum(s.value.SPACER_HEIGHT_MOBILE, Math.max(16, Math.round(height.value / 2)))
+  );
+  const showLine = computed(() => toBool(s.value.SHOW_LINE ?? s.value.SHOW_DIVIDER));
+  const lineColor = computed(() => s.value.LINE_COLOR || s.value.DIVIDER_COLOR || '');
+
+  return { s, scheme, customClass, toNum, toBool, height, heightMobile, showLine, lineColor };
+}

package/app/logic/sections/SplitShowcaseSection.js

@@ -0,0 +1,6 @@
+
+export default function useLogic() {
+
+
+  return {  };
+}

package/app/logic/sections/TestimonialListSection.js

@@ -0,0 +1,6 @@
+
+export default function useLogic() {
+  const ROOT_DEFAULTS = { DIRECTION: "VERTICAL", ALIGNMENT: "CENTER", POSITION: "TOP", GAP: 32 };
+
+  return { ROOT_DEFAULTS };
+}

package/app/logic/sections/VideoSection.js

@@ -0,0 +1,235 @@
+
+export default function useLogic({ props }) {
+  const { s, t, shellStyle, innerStyle, customClass } = useSectionShell(() => props.section);
+  const { mediaUrl } = useMediaUrl();
+  const { isMobile } = useLayoutShell();
+
+  const { tree, editing, u } = useContentTree(() => props.section, {
+    rootDefaults: { DIRECTION: "VERTICAL", ALIGNMENT: "CENTER", POSITION: "CENTER", GAP: 16 },
+    index: () => props.index,
+  });
+  const { num, px, compact, upper } = u;
+
+  /* ----------------------------------------------------------------- source */
+
+  const source = computed(() => {
+    const chosen = upper(s.value.VIDEO_SOURCE, "");
+    if (chosen === "UPLOAD" || chosen === "LINK") return chosen;
+    return s.value.VIDEO_URL ? "LINK" : "UPLOAD";
+  });
+
+  /** { kind: 'file' | 'youtube' | 'vimeo', src | id } or null. */
+  const video = computed(() => {
+    const v = s.value;
+    if (source.value === "UPLOAD") {
+      const media = (isMobile.value && v.MOBILE_VIDEO_MEDIA) || v.VIDEO_MEDIA;
+      const src = mediaUrl(media ?? null);
+      return src ? { kind: "file", src } : null;
+    }
+    const url = String(v.VIDEO_URL ?? "").trim();
+    if (!url) return null;
+    const yt = url.match(/(?:youtu\.be\/|watch\?v=|\/embed\/|\/shorts\/|\/live\/)([A-Za-z0-9_-]{11})/);
+    if (yt) return { kind: "youtube", id: yt[1] };
+    const vm = url.match(/vimeo\.com\/(?:video\/)?(\d+)/);
+    if (vm) return { kind: "vimeo", id: vm[1] };
+    if (/^https?:\/\//i.test(url)) return { kind: "file", src: url };
+    return null;
+  });
+
+  const poster = computed(() => {
+    const own = mediaUrl(s.value.POSTER ?? null);
+    if (own) return own;
+    // YouTube publishes a still for every video; better than a black box.
+    return video.value?.kind === "youtube" ? `https://i.ytimg.com/vi/${video.value.id}/hqdefault.jpg` : "";
+  });
+  const label = computed(() => t(s.value.VIDEO_ALT) || "Video");
+
+  /* --------------------------------------------------------------- playback */
+
+  const reducedMotion = ref(false);
+  const autoplay = computed(() => !!s.value.AUTOPLAY && !reducedMotion.value);
+  const loop = computed(() => s.value.LOOP !== false);
+  const controls = computed(() => s.value.SHOW_CONTROLS !== false);
+  const startMuted = computed(() => autoplay.value || s.value.MUTED !== false);
+
+  /** A clicked (non-autoplay) video is playing: hide the cover and content. */
+  const playing = ref(false);
+  /** Embeds: the iframe exists (autoplay, or after the click). */
+  const embedLoaded = ref(false);
+
+  const embedSrc = computed(() => {
+    const v = video.value;
+    if (!v || v.kind === "file") return null;
+    const auto = autoplay.value || embedLoaded.value;
+    const muted = autoplay.value ? 1 : startMuted.value && !playing.value ? 1 : 0;
+    if (v.kind === "youtube") {
+      const q = new URLSearchParams({
+        autoplay: auto ? "1" : "0",
+        mute: String(muted),
+        controls: controls.value ? "1" : "0",
+        loop: loop.value ? "1" : "0",
+        playlist: v.id, // YouTube only loops a playlist — of this one video
+        playsinline: "1",
+        rel: "0",
+        modestbranding: "1",
+      });
+      return `https://www.youtube-nocookie.com/embed/${v.id}?${q}`;
+    }
+    const q = new URLSearchParams({
+      autoplay: auto ? "1" : "0",
+      muted: String(muted),
+      loop: loop.value ? "1" : "0",
+      controls: controls.value ? "1" : "0",
+      // Vimeo's chromeless, silent, looping mode — for autoplay without controls.
+      background: autoplay.value && !controls.value ? "1" : "0",
+      playsinline: "1",
+      dnt: "1",
+    });
+    return `https://player.vimeo.com/video/${v.id}?${q}`;
+  });
+
+  // ---- self-hosted files: load when near the viewport, play/pause with it
+  const videoEl = ref(null);
+  let observer = null;
+
+  function attach(el) {
+    observer?.disconnect();
+    if (!el || typeof window === "undefined" || !("IntersectionObserver" in window)) return;
+    observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          if (!el.getAttribute("src") && el.dataset.src) {
+            el.src = el.dataset.src;
+            el.load();
+          }
+          if (autoplay.value) el.play().catch(() => {});
+        } else if (autoplay.value) {
+          el.pause();
+        }
+      },
+      { rootMargin: "200px 0px", threshold: 0.01 }
+    );
+    observer.observe(el);
+  }
+
+  watch(videoEl, attach);
+  // A new file (edited in the builder) must replace what's loaded.
+  watch(() => video.value?.src, () => {
+    const el = videoEl.value;
+    if (!el) return;
+    el.removeAttribute("src");
+    playing.value = false;
+    attach(el);
+  });
+
+  onMounted(() => {
+    reducedMotion.value = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+    if (autoplay.value && video.value && video.value.kind !== "file") embedLoaded.value = true;
+  });
+  onBeforeUnmount(() => observer?.disconnect());
+
+  async function play() {
+    const v = video.value;
+    if (!v) return;
+    if (v.kind !== "file") {
+      // Embeds: there's no reliable "frames are now rendering" event without
+      // the platform's postMessage API, and the iframe shows its own
+      // thumbnail while it buffers — so there's no bare gap to bridge here.
+      playing.value = true;
+      embedLoaded.value = true;
+      return;
+    }
+    const el = videoEl.value;
+    if (!el) return;
+    if (!el.getAttribute("src")) {
+      el.src = el.dataset.src;
+      el.load();
+    }
+    el.muted = startMuted.value;
+    el.controls = controls.value;
+    try {
+      await el.play();
+      // Don't flip `playing` here — el.play() resolving just means playback
+      // was *requested*, not that a frame is on screen yet. Wait for the
+      // native 'playing' event (below) so the cover stays up, unbroken,
+      // until the video is actually visible — no gap, no re-flash of poster.
+    } catch {
+      playing.value = false;
+    }
+  }
+
+  function onPause() {
+    if (!autoplay.value) playing.value = false;
+  }
+  function onPlaying() {
+    if (!autoplay.value) playing.value = true;
+  }
+
+  const showCover = computed(() => {
+    const v = video.value;
+    if (!v || autoplay.value) return false;
+    return v.kind === "file" ? !playing.value : !embedLoaded.value;
+  });
+
+  /* ------------------------------------------------------------------ sizing */
+
+  const RATIOS = { WIDE: "16 / 9", CLASSIC: "4 / 3", SQUARE: "1 / 1", PORTRAIT: "4 / 5", VERTICAL: "9 / 16", CINEMA: "21 / 9" };
+  const HEIGHTS = { SMALL: "40vh", MEDIUM: "60vh", LARGE: "80vh", FULL: "100svh" };
+
+  const frameVars = computed(() => {
+    const v = s.value;
+    const height = upper(v.HEIGHT, "RATIO");
+    const ratio = RATIOS[upper(v.RATIO, "WIDE")] ?? RATIOS.WIDE;
+    const mobileRatio = RATIOS[upper(v.RATIO_MOBILE, "")];
+    const fixed = height === "CUSTOM" ? px(num(v.HEIGHT_CUSTOM, 560)) : HEIGHTS[height];
+    const pad = num(v.CONTENT_PADDING, 40);
+    return compact({
+      "--vs-w": `${num(v.VIDEO_WIDTH, 100)}%`,
+      "--vs-w-m": `${num(v.VIDEO_WIDTH_MOBILE, 100)}%`,
+      // Desktop: a ratio or a height. Phones: RATIO_MOBILE wins, else the same.
+      "--vs-ratio": fixed ? "auto" : ratio,
+      "--vs-h": fixed ?? "auto",
+      "--vs-ratio-m": mobileRatio ?? (fixed ? "auto" : ratio),
+      "--vs-h-m": mobileRatio ? "auto" : fixed ?? "auto",
+      "--vs-fit": upper(v.FIT, "COVER") === "CONTAIN" ? "contain" : "cover",
+      "--vs-radius": px(v.VIDEO_RADIUS),
+      "--vs-border":
+        upper(v.BORDER_STYLE, "NONE") === "SOLID"
+          ? `${num(v.BORDER_WIDTH, 1)}px solid ${v.BORDER_COLOR || "currentColor"}`
+          : undefined,
+      "--vs-pad": `${pad}px`,
+      "--vs-pad-m": `${num(v.CONTENT_PADDING_MOBILE, pad)}px`,
+      "--vs-text": v.CONTENT_TEXT_COLOR,
+    });
+  });
+
+  const overlay = computed(() => {
+    const opacity = num(s.value.OVERLAY_OPACITY, 0);
+    return opacity > 0 ? { background: s.value.OVERLAY_COLOR || "#000", opacity: opacity / 100 } : null;
+  });
+
+  /* ----------------------------------------------------------------- content */
+
+  const POSITIONS = ["OVERLAY", "BELOW", "ABOVE"];
+  const position = computed(() => {
+    const p = upper(s.value.CONTENT_POSITION, "OVERLAY");
+    return POSITIONS.includes(p) ? p : "OVERLAY";
+  });
+  const positionMobile = computed(() => {
+    const p = upper(s.value.CONTENT_POSITION_MOBILE, "");
+    return POSITIONS.includes(p) ? p : position.value;
+  });
+  const hasContent = computed(() => tree.value.children.length > 0 || editing.value);
+
+  const frameClasses = computed(() => [
+    `pos-${position.value.toLowerCase()}`,
+    `mpos-${positionMobile.value.toLowerCase()}`,
+    {
+      "is-playing": playing.value && !autoplay.value,
+      "fit-contain": upper(s.value.FIT, "COVER") === "CONTAIN",
+      "has-content": hasContent.value,
+    },
+  ]);
+
+  return { s, t, shellStyle, innerStyle, customClass, mediaUrl, isMobile, tree, editing, u, num, px, compact, upper, source, video, poster, label, reducedMotion, autoplay, loop, controls, startMuted, playing, embedLoaded, embedSrc, videoEl, observer, attach, play, onPause, onPlaying, showCover, RATIOS, HEIGHTS, frameVars, overlay, POSITIONS, position, positionMobile, hasContent, frameClasses };
+}

package/app/pages/[category]/[product].vue

@@ -0,0 +1,196 @@
+<script setup>
+import { useRenderContext } from "#osi/composables/useRenderContext";
+import { useProductResource } from "#osi/composables/useProductDetail";
+
+/**
+ * Product detail — `/<category-slug>/<product-slug>`.
+ *
+ * Same three lines every theme-driven route has: ask the backend which template
+ * serves this path, publish the payload, hand the sections to SectionRenderer.
+ * The layout of a product page lives in MAIN_PRODUCT, not here.
+ *
+ * ⚠ Backend prerequisite — `resolve_path()` has to match a two-segment path to
+ * the PRODUCT template, and match it LAST so it can't shadow the prefixes:
+ *
+ *     /categories/<slug>   CLASSIFICATION
+ *     /collections/<slug>  CLASSIFICATION
+ *     /pages/<handle>      PAGE
+ *     /products/<slug>     PRODUCT   (keep — uncategorised products use it)
+ *     /<category>/<slug>   PRODUCT   ← last
+ *
+ * This file serves `/products/<slug>` too: it's just this route with
+ * `category === "products"`, and useProductResource only reads the second
+ * segment.
+ *
+ * The product itself is awaited here rather than in the section so it lands in
+ * the SSR payload — the section re-reads it from cache.
+ */
+definePageMeta({ name: "product-detail" });
+
+// Every composable is called before the first await. On the server the async
+// context is lost across an arbitrary await, and anything reaching for
+// useState() or useRequestHeaders() afterwards throws — see the same note in
+// useStorefront().
+const route = useRoute();
+const { render, store } = useStorefront();
+const { setRenderContext } = useRenderContext();
+const { mediaUrl } = useMediaUrl();
+const origin = useRequestURL().origin;
+
+// Both fetches start here; useAsyncData runs its handler immediately, so
+// awaiting them one after the other still overlaps the two round trips.
+const productResource = useProductResource();
+const renderData = useAsyncData(`render:${route.path}`, () => render(route.path));
+
+await productResource.asyncData;
+const { data: rendered, error } = await renderData;
+
+// The 404 thrown inside useProductResource's fetch only lands in its `error`
+// ref — useAsyncData doesn't rethrow. Surface it here. From this point on the
+// product exists; the only question is which sections to use.
+const productError = productResource.error.value;
+if (!productResource.asyncData.data.value) {
+  throw createError({
+    statusCode: productError?.statusCode === 500 ? 500 : 404,
+    statusMessage: productError?.statusCode === 500 ? "Couldn't load this product" : "Product not found",
+    fatal: true,
+  });
+}
+
+const MAIN = "MAIN_PRODUCT";
+const defaultSections = () => [
+  { key: "main-product", type: MAIN, settings: {}, blocks: [] },
+  { key: "product-recommendations", type: "PRODUCT_RECOMMENDATIONS", settings: {}, blocks: [] },
+];
+
+const templateName = (payload) => {
+  const t = payload?.template;
+  return String((t && typeof t === "object" ? t.name : t) ?? "").toUpperCase();
+};
+
+/**
+ * render() answers a path it can't route with the NOT_FOUND template (200) or
+ * a 404 — not the product page. That's the difference between the preview
+ * (the dashboard sends the PRODUCT template's sections directly) and the live
+ * page (which only gets them if resolve_path() matches /<category>/<slug>).
+ * Only a PRODUCT payload counts.
+ */
+const isProductPayload = (payload) => {
+  if (!payload) return false;
+  const name = templateName(payload);
+  return !name || name === "PRODUCT";
+};
+
+/**
+ * Not routed as /<category>/<slug>? Every product shares the PRODUCT template,
+ * so the same product under /products/<slug> — the path resolve_path() has
+ * always matched — returns exactly the merchant's sections.
+ */
+const productSlug = String(route.params.product ?? "");
+const altPath = productSlug && route.params.category !== "products" ? `/products/${productSlug}` : null;
+const alt =
+  !isProductPayload(rendered.value) && altPath
+    ? await useAsyncData(`render:${altPath}`, () => render(altPath))
+    : { data: ref(null) };
+
+const source = computed(() => {
+  if (isProductPayload(rendered.value)) return rendered.value;
+  if (isProductPayload(alt.data.value)) return alt.data.value;
+  return null;
+});
+
+/** What the page renders: the template's sections, MAIN_PRODUCT always there. */
+const data = computed(() => {
+  const base = source.value;
+  const sections = base?.sections ?? [];
+  const product = productResource.product.value;
+  return {
+    ...(base ?? { template: "PRODUCT", seo: {} }),
+    resource: base?.resource ?? (product ? { type: "PRODUCT", id: product.id, slug: productSlug } : null),
+    sections: !sections.length
+      ? defaultSections()
+      : sections.some((section) => section.type === MAIN)
+      ? sections
+      : [{ key: "main-product", type: MAIN, settings: {}, blocks: [] }, ...sections],
+  };
+});
+
+if (import.meta.dev && !isProductPayload(rendered.value)) {
+  console.warn(
+    `[product] render() did not resolve ${route.path} to PRODUCT` +
+      (source.value ? `; using the template from ${altPath}.` : "; using the default layout.") +
+      " resolve_path() needs to match /<category>/<slug> (last, after the prefixes).",
+    error.value ?? ""
+  );
+}
+
+setRenderContext(data.value);
+watch(data, (payload) => setRenderContext(payload));
+
+/* ------------------------------------------------------------------- SEO */
+
+const product = productResource.product;
+const seo = computed(() => data.value?.seo ?? {});
+
+const description = computed(() => {
+  const explicit = seo.value.description;
+  if (explicit) return explicit;
+  return String(product.value?.description ?? "")
+    .replace(/<[^>]*>?/gm, "")
+    .trim()
+    .slice(0, 300);
+});
+
+const image = computed(() => {
+  if (seo.value.image) return seo.value.image;
+  const path = product.value?.main_image?.path;
+  return path ? mediaUrl(path) : undefined;
+});
+
+const title = computed(
+  () =>
+    seo.value.title_full ??
+    seo.value.title ??
+    [product.value?.name, store.value?.name].filter(Boolean).join(" | ")
+);
+
+// view_item / ViewContent — once per product per visit to the page. `product`
+// can change under the same route component (client-side navigation between
+// two products), hence the watch rather than onMounted.
+const analytics = useAnalytics();
+if (import.meta.client) {
+  watch(
+    () => product.value?.id,
+    () => {
+      const current = product.value;
+      if (current && !current.is_placeholder) analytics.viewItem(current);
+    },
+    { immediate: true, flush: "post" }
+  );
+}
+
+useHead({
+  title,
+  titleTemplate: (value) => value ?? "",
+  meta: () => [
+    { name: "description", content: description.value || undefined },
+    { property: "og:type", content: "product" },
+    { property: "og:title", content: product.value?.name || undefined },
+    { property: "og:description", content: description.value || undefined },
+    { property: "og:image", content: image.value },
+    { name: "twitter:card", content: "summary_large_image" },
+    { name: "twitter:title", content: product.value?.name || undefined },
+    { name: "twitter:description", content: description.value || undefined },
+    { name: "twitter:image", content: image.value },
+    { name: "robots", content: seo.value.no_index ? "noindex, nofollow" : "index, follow" },
+  ],
+  link: () =>
+    seo.value.canonical_path ? [{ rel: "canonical", href: `${origin}${seo.value.canonical_path}` }] : [],
+});
+</script>
+
+<template>
+  <div>
+    <SectionRenderer :sections="data.sections" />
+  </div>
+</template>

package/app/pages/__builder-preview.vue

@@ -0,0 +1,38 @@
+<script setup>
+/**
+ * Theme Builder Preview Page.
+ *
+ * Lightweight shell rendered inside the dashboard's iframe. Does NOT make its
+ * own API calls — the builder sends the full state immediately after the READY
+ * handshake via postMessage, and every subsequent edit pushes a new STATE.
+ *
+ * This keeps first-paint fast (no SSR data-fetch) and guarantees the preview
+ * is always driven by the builder's in-memory state, not a stale DB snapshot.
+ */
+import { BuilderOverlay } from "#components";
+
+const { sectionsFrom } = useBuilderPreview();
+const sections = sectionsFrom(ref([]));
+</script>
+
+<template>
+  <div>
+    <SectionRenderer v-if="sections?.length" :sections="sections" />
+    <div v-else class="osi-empty">
+      <p>Waiting for builder…</p>
+    </div>
+
+    <!-- Hover / selection outlines, name tags, toolbar and "+" buttons. -->
+    <BuilderOverlay />
+  </div>
+</template>
+
+<style scoped>
+.osi-empty {
+  padding: 6rem 1rem;
+  text-align: center;
+  color: var(--osi-text, #999);
+  opacity: 0.7;
+  font-family: system-ui, sans-serif;
+}
+</style>