@antelopejs/dms 0.9.1 → 0.9.3

package/dist/utils/user-activity.d.ts

@@ -1,4 +1,4 @@
 import type { User, UserModel } from "@antelopejs/interface-dms/auth/db";
 export declare const USER_ACTIVITY_WRITE_INTERVAL_MS: number;
 export declare function isActivityWriteDue(lastActiveAt: Date | null | undefined, now: Date): boolean;
-export declare function recordUserActivity(userModel: UserModel, user: User, now?: Date): void;
+export declare function recordUserActivity(userModel: UserModel, user: User, now?: Date): Promise<void>;

package/dist/utils/user-activity.js

@@ -11,12 +11,15 @@ function isActivityWriteDue(lastActiveAt, now) {
     const elapsed = now.getTime() - new Date(lastActiveAt).getTime();
     return elapsed >= exports.USER_ACTIVITY_WRITE_INTERVAL_MS;
 }
-function recordUserActivity(userModel, user, now = new Date()) {
+async function recordUserActivity(userModel, user, now = new Date()) {
     if (!isActivityWriteDue(user.lastActiveAt, now))
         return;
     user.lastActiveAt = now;
-    userModel.update(user).catch((error) => {
+    try {
+        await userModel.update(user);
+    }
+    catch (error) {
         logging_1.Logging.Warn(`[dms] could not record the activity of "${user._id}"`, error);
-    });
+    }
 }
 //# sourceMappingURL=user-activity.js.map

package/dist/utils/user-activity.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-activity.js","sourceRoot":"","sources":["../../src/utils/user-activity.ts"],"names":[],"mappings":";;;AAgBA,gDAOC;AAUD,gDAYC;AA7CD,gEAA6D;AAQhD,QAAA,+BAA+B,GAAG,EAAE,GAAG,IAAI,CAAC;AAQzD,SAAgB,kBAAkB,CAChC,YAAqC,EACrC,GAAS;IAET,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO,OAAO,IAAI,uCAA+B,CAAC;AACpD,CAAC;AAUD,SAAgB,kBAAkB,CAChC,SAAoB,EACpB,IAAU,EACV,MAAY,IAAI,IAAI,EAAE;IAEtB,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC;QAAE,OAAO;IACxD,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC;IAGxB,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC9C,iBAAO,CAAC,IAAI,CAAC,2CAA2C,IAAI,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"user-activity.js","sourceRoot":"","sources":["../../src/utils/user-activity.ts"],"names":[],"mappings":";;;AAgBA,gDAOC;AAaD,gDAcC;AAlDD,gEAA6D;AAQhD,QAAA,+BAA+B,GAAG,EAAE,GAAG,IAAI,CAAC;AAQzD,SAAgB,kBAAkB,CAChC,YAAqC,EACrC,GAAS;IAET,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO,OAAO,IAAI,uCAA+B,CAAC;AACpD,CAAC;AAaM,KAAK,UAAU,kBAAkB,CACtC,SAAoB,EACpB,IAAU,EACV,MAAY,IAAI,IAAI,EAAE;IAEtB,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC;QAAE,OAAO;IACxD,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC;IAGxB,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,iBAAO,CAAC,IAAI,CAAC,2CAA2C,IAAI,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}

package/frontend-vue/dms.frontend.ts

@@ -165,8 +165,10 @@ function registerPlugins(sdk: Parameters<DmsFrontendModule["setup"]>[0]): void {
       await plugin.default(context);
     }, clientOnly);
   }
-  // Before any data is read: every key lives in the session's scope.
-  sdk.registerPlugin(asyncDataScopePlugin);
+  // Before any data is read, a higher-priority module's plugins included:
+  // every key lives in the session's scope, and a new scope aborts the reads
+  // started before it.
+  sdk.registerPlugin(asyncDataScopePlugin, { enforce: "pre" });
   // First: the requests the middlewares wait on start with the app, alongside
   // the ones the plugins below and the page make, instead of one after the
   // other once the page has set up.

package/frontend-vue/layers/dms-core/app/composables/user/useUserRegionalPreferences.ts

@@ -1,6 +1,7 @@
 import {
   browserTimeZone,
   localeWeekStart,
+  readerTimeZone,
   readRegionalPreferences,
   type RegionalPreferenceFields,
   type RegionalPreferences,
@@ -33,7 +34,9 @@ export function useUserRegionalPreferences() {
   const preferences = computed<RegionalPreferences>(() =>
     readRegionalPreferences(user.value),
   );
-  const detectedTimeZone = browserTimeZone();
+  // On a server, the zone of the browser the page is for (its cookie), so the
+  // server renders the zone the browser hydrates with.
+  const detectedTimeZone = readerTimeZone() ?? browserTimeZone();
   const timeZone = computed(
     () => preferences.value.timeZone ?? detectedTimeZone,
   );

package/frontend-vue/layers/dms-core/app/types/menu.ts

@@ -7,8 +7,9 @@ export type MenuItemVariant = "default" | "accent";
 export type MenuItemStatus = "success" | "warning" | "error" | "neutral";
 
 /**
- * Tone of a counted menu badge, mirroring `Tone` in the backend: the server
- * serves it as `badgeTone` next to `badge`; neutral when absent.
+ * Tone of a counted menu badge, mirroring `Tone` in the backend: the page's
+ * `navBadges` entry carries it next to `badge` (`{ badge, tone? }`); neutral
+ * when absent.
  */
 export type MenuItemBadgeTone =
   | "neutral"

package/frontend-vue/layers/dms-layout/app/assets/css/main.css

@@ -30,35 +30,35 @@
   }
 }
 
-/* Self-hosted Geist (SIL OFL 1.1, files in /public/fonts + LICENSE.txt).
+/* Self-hosted Geist (SIL OFL 1.1, files and LICENSE.txt in ../fonts).
    Variable files cover weights 100–900 and keep builds deterministic offline. */
 @font-face {
   font-family: "Geist";
   font-style: normal;
   font-weight: 100 900;
   font-display: swap;
-  src: url("/fonts/Geist-Variable.woff2") format("woff2");
+  src: url("../fonts/Geist-Variable.woff2") format("woff2");
 }
 @font-face {
   font-family: "Geist";
   font-style: italic;
   font-weight: 100 900;
   font-display: swap;
-  src: url("/fonts/Geist-Italic-Variable.woff2") format("woff2");
+  src: url("../fonts/Geist-Italic-Variable.woff2") format("woff2");
 }
 @font-face {
   font-family: "Geist Mono";
   font-style: normal;
   font-weight: 100 900;
   font-display: swap;
-  src: url("/fonts/GeistMono-Variable.woff2") format("woff2");
+  src: url("../fonts/GeistMono-Variable.woff2") format("woff2");
 }
 @font-face {
   font-family: "Geist Mono";
   font-style: italic;
   font-weight: 100 900;
   font-display: swap;
-  src: url("/fonts/GeistMono-Italic-Variable.woff2") format("woff2");
+  src: url("../fonts/GeistMono-Italic-Variable.woff2") format("woff2");
 }
 
 /* Interface scale: Nuxt UI / Tailwind sizing is rem-based, so scaling the

package/frontend-vue/layers/dms-layout/app/composables/page/usePageComponentPreload.ts

@@ -12,8 +12,11 @@ function collectFromComponentInfo(
 }
 
 /**
- * Collect every componentName referenced by a page layout: the layout
- * component itself, the top-level components and all their nested children.
+ * Collect every componentName referenced by a page layout: the top-level
+ * components and all their nested children, and the children of the layout
+ * component. The layout component itself is a layout the frontend modules
+ * register apart from components (`registerLayout`), which the renderer
+ * loads with the page: looked up among the components, it is not found.
  */
 export function collectPageLayoutComponentNames(
   layout: PageLayout | null | undefined,
@@ -21,7 +24,9 @@ export function collectPageLayoutComponentNames(
   if (!layout) return [];
 
   const names = new Set<string>();
-  collectFromComponentInfo(layout.layout, names);
+  for (const child of layout.layout?.children || []) {
+    collectFromComponentInfo(child.component, names);
+  }
   for (const info of Object.values(layout.components || {})) {
     collectFromComponentInfo(info, names);
   }

package/frontend-vue/layers/dms-layout/app/custom-layouts/PreviewLayout.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+defineOptions({
+  inheritAttrs: false,
+});
+</script>
+
+<template>
+  <!-- The block preview's frame: nothing around the blocks, so an embedding
+       page sizes the iframe to them and a capture crops to them. -->
+  <main class="bg-default" data-dms-page-content>
+    <slot />
+  </main>
+</template>
+
+<style>
+/* A transparent preview (`transparent: true`) lets the embedding page's own
+   background show through the iframe, e.g. a docs site in dark mode. */
+html:has([data-dms-preview-transparent]),
+html:has([data-dms-preview-transparent]) body,
+html:has([data-dms-preview-transparent]) [data-dms-page-content] {
+  background: transparent;
+}
+
+/* A browser paints an opaque backdrop behind an iframe whose color scheme
+   differs from the embedding page's: declare the theme's own scheme, so a dark
+   docs page (`color-scheme: dark`) shows through a dark preview. */
+html.dark:has([data-dms-preview-transparent]) {
+  color-scheme: dark;
+}
+
+html.light:has([data-dms-preview-transparent]) {
+  color-scheme: light;
+}
+</style>

package/frontend-vue/layers/dms-layout/app/plugins/font-preload.ts

@@ -1,23 +1,25 @@
-// The two faces every page sets its text in. Fetched only once the stylesheet
-// is parsed, they landed after the first paint, and the swap from the
-// fallback face moved the header and the page text (wider breadcrumbs, other
-// line breaks). Preloaded from the head, they are there for the first paint.
-const PRELOADED_FONTS = [
-  "/fonts/Geist-Variable.woff2",
-  "/fonts/GeistMono-Variable.woff2",
-];
+// The face every page sets its text in. Fetched only once the stylesheet is
+// parsed, it landed after the first paint, and the swap from the fallback face
+// moved the header and the page text (wider breadcrumbs, other line breaks).
+// Preloaded from the head, it is there for the first paint. Imported rather
+// than named, so it is the build's own file: named after its content, cached
+// for good, the same file the stylesheet's `@font-face` asks for.
+import geistVariable from "../assets/fonts/Geist-Variable.woff2";
+
 const FONT_TYPE = "font/woff2";
 
-/** Server only: the links only matter in the server-rendered head. */
+/** Server only: the link only matters in the server-rendered head. */
 export default defineDmsPlugin(() => {
   if (!import.meta.env.SSR) return;
   useHead({
-    link: PRELOADED_FONTS.map((href) => ({
-      rel: "preload",
-      as: "font",
-      type: FONT_TYPE,
-      href,
-      crossorigin: "anonymous",
-    })),
+    link: [
+      {
+        rel: "preload",
+        as: "font",
+        type: FONT_TYPE,
+        href: geistVariable,
+        crossorigin: "anonymous",
+      },
+    ],
   });
 });

package/frontend-vue/layers/dms-layout/i18n/locales/layout-en-GB.json

@@ -711,6 +711,9 @@
         "member": "Member",
         "two_factor_on_short": "On"
       }
+    },
+    "dms_preview": {
+      "title": "Block preview"
     }
   },
   "modules": {

package/frontend-vue/layers/dms-layout/i18n/locales/layout-fr-FR.json

@@ -715,6 +715,9 @@
         "member": "Membre",
         "two_factor_on_short": "Activée"
       }
+    },
+    "dms_preview": {
+      "title": "Aperçu de blocs"
     }
   },
   "modules": {

package/frontend-vue/layers/dms-onboarding/app/middleware/onboarding.global.ts

@@ -1,5 +1,8 @@
 const ONBOARDING_PATH = "/onboarding";
 const LOGIN_PATH = "/auth";
+// The block preview a docs site embeds draws blocks only, so an instance not
+// yet set up still serves it rather than the wizard.
+const BLOCK_PREVIEW_PATH = "/dms-preview";
 
 // Where a visit to the finished wizard lands: the app for a signed-in user, the
 // login page for anyone else rather than a homepage whose 401 would bounce
@@ -10,6 +13,7 @@ function completedOnboardingDestination(): string {
 }
 
 export default defineDmsMiddleware(async (to) => {
+  if (to.path === BLOCK_PREVIEW_PATH) return;
   const isOnboardingRoute = to.path.startsWith(ONBOARDING_PATH);
 
   // While the instance has no admin yet, funnel every route to the onboarding

package/frontend-vue/layers/dms-ui/app/build/components/block-preview/BlockPreviewIssue.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import type { PreviewIssue } from "../../utils/blockPreview";
+
+defineOptions({ inheritAttrs: false });
+
+const props = defineProps<{ issue: PreviewIssue }>();
+
+const { t } = useI18n();
+const message = computed(() =>
+  t(`dms.block_preview.${props.issue.key}`, {
+    name: props.issue.name,
+    value: props.issue.value ?? "",
+  }),
+);
+</script>
+
+<template>
+  <UAlert
+    color="warning"
+    variant="subtle"
+    icon="i-ph-warning"
+    :title="message"
+    data-dms-preview-issue
+  />
+</template>

package/frontend-vue/layers/dms-ui/app/build/components/sortable/SortableList.vue

@@ -0,0 +1,144 @@
+<script setup lang="ts" generic="Item">
+/**
+ * A list whose items the user reorders by dragging, or moves to another list
+ * of the same `group`: SortableJS, through VueUse's `useSortable`.
+ *
+ * SortableJS moves the dragged element in the DOM itself. Vue owns these
+ * elements, so each drop puts the element back where it was and updates the
+ * `list` model with a new array instead, from which Vue renders the new
+ * order. `change` then says what happened to this list: `moved` within it,
+ * `added` from another one, `removed` to another one.
+ */
+import { useSortable } from "@vueuse/integrations/useSortable";
+import { ref, watch } from "vue";
+
+export interface SortableListChange<Item> {
+  added?: { element: Item; newIndex: number };
+  removed?: { element: Item; oldIndex: number };
+  moved?: { element: Item; oldIndex: number; newIndex: number };
+}
+
+/** The items, in order: a new array after each drop. */
+const list = defineModel<Item[]>("list", { required: true });
+
+const props = defineProps<{
+  /** A stable key of an item: Vue keeps each element with its item. */
+  itemKey: (item: Item) => PropertyKey | undefined;
+  /** Lists sharing a group exchange items. */
+  group?: string;
+  disabled?: boolean;
+  /** Only an item grabbed by an element matching this selector moves. */
+  handle?: string;
+  /** Items matching this selector stay in place. */
+  filter?: string;
+  /** Class of the slot the dragged item will land in. */
+  ghostClass?: string;
+  /** Class of the item while it follows the pointer. */
+  dragClass?: string;
+}>();
+
+const emit = defineEmits<{ change: [change: SortableListChange<Item>] }>();
+
+defineSlots<{ item(props: { element: Item; index: number }): unknown }>();
+
+/** What this list reads of SortableJS's events. */
+interface SortableEvent {
+  item: HTMLElement;
+  oldIndex?: number;
+  newIndex?: number;
+}
+
+const draggedKey = () => props.group ?? "";
+
+const root = ref<HTMLElement | null>(null);
+
+/**
+ * Where the dragged element stood. Next to the node that followed it, not at
+ * an index: Vue removes an item by the markers around it, which an index
+ * among the elements does not see.
+ */
+let origin: { parent: Node; next: Node | null } | undefined;
+
+/** Put the element SortableJS moved back where Vue rendered it. */
+function restore(item: HTMLElement) {
+  if (origin) origin.parent.insertBefore(item, origin.next);
+}
+
+/** `list` without its item at `index`, and that item. */
+function without(index: number): [Item[], Item | undefined] {
+  const next = [...list.value];
+  const [element] = next.splice(index, 1);
+  return [next, element];
+}
+
+const { option } = useSortable(root, list, {
+  group: props.group,
+  disabled: props.disabled,
+  handle: props.handle,
+  filter: props.filter,
+  // A filtered item still gets its click: a locked card opens like the others.
+  preventOnFilter: false,
+  ghostClass: props.ghostClass,
+  dragClass: props.dragClass,
+  onStart: (event: SortableEvent) => {
+    const { parentNode, nextSibling } = event.item;
+    origin = parentNode ? { parent: parentNode, next: nextSibling } : undefined;
+    const element = list.value[event.oldIndex ?? -1];
+    if (element !== undefined) sharedDragged.set(draggedKey(), element);
+  },
+  onUpdate: (event: SortableEvent) => {
+    const { oldIndex, newIndex } = event;
+    if (oldIndex === undefined || newIndex === undefined) return;
+    restore(event.item);
+    const [next, element] = without(oldIndex);
+    if (element === undefined) return;
+    next.splice(newIndex, 0, element);
+    list.value = next;
+    emit("change", { moved: { element, oldIndex, newIndex } });
+  },
+  onAdd: (event: SortableEvent) => {
+    const element = sharedDragged.get(draggedKey()) as Item | undefined;
+    const { newIndex } = event;
+    if (element === undefined || newIndex === undefined) return;
+    // The element goes back to the list it left, which removes it below.
+    event.item.remove();
+    const next = [...list.value];
+    next.splice(newIndex, 0, element);
+    list.value = next;
+    emit("change", { added: { element, newIndex } });
+  },
+  onRemove: (event: SortableEvent) => {
+    const { oldIndex } = event;
+    if (oldIndex === undefined) return;
+    restore(event.item);
+    const [next, element] = without(oldIndex);
+    if (element === undefined) return;
+    list.value = next;
+    emit("change", { removed: { element, oldIndex } });
+  },
+  onEnd: () => {
+    origin = undefined;
+    sharedDragged.delete(draggedKey());
+  },
+});
+
+watch(
+  () => props.disabled,
+  (disabled) => option("disabled", disabled),
+);
+</script>
+
+<script lang="ts">
+// The item being dragged, by group. A drop on another list only names the
+// element, which belongs to the list it left: the list it lands in reads the
+// item the other one stored when the drag started.
+const sharedDragged = new Map<string, unknown>();
+</script>
+
+<template>
+  <div ref="root">
+    <template v-for="(element, index) in list" :key="itemKey(element)">
+      <slot name="item" :element="element" :index="index" />
+    </template>
+  </div>
+</template>

package/frontend-vue/layers/dms-ui/app/build/components/table/MenuColumns.vue

@@ -4,10 +4,10 @@ import type { Column } from "@tanstack/vue-table";
 import { tv } from "tailwind-variants";
 import type { DmsAppConfig } from "#dms-core/shared/types/app-config";
 import type { ShallowRef } from "vue";
-import Draggable from "vuedraggable";
 
 import type { TableSharedData, Data } from "./Table.vue";
 import type { TableColumnMeta } from "../../composables/table/types";
+import SortableList from "../sortable/SortableList.vue";
 
 const theme = tv({
   slots: {
@@ -40,20 +40,21 @@ const rawColumns = computed(
   () => tableSharedData?.value?.table.getAllColumns() || [],
 );
 
-const columns = computed({
-  get() {
-    return mapColumns();
-  },
-  set(newValue) {
-    if (!tableSharedData?.value) return;
-    const updatedOrder = [
-      "select",
-      ...newValue.map((col) => col.id),
-      "actions",
-    ];
-    tableSharedData.value.columnOrderState.value = [...updatedOrder];
-  },
-});
+const columns = computed(() => mapColumns());
+type ListedColumn = (typeof columns.value)[number];
+
+// A drag gives the columns in their new order; `select` stays first and
+// `actions` last.
+function applyColumnOrder(ordered: ListedColumn[]) {
+  if (!tableSharedData?.value) return;
+  tableSharedData.value.columnOrderState.value = [
+    "select",
+    ...ordered.map((col) => col.id),
+    "actions",
+  ];
+}
+
+const columnKey = (column: ListedColumn) => column.id;
 
 function mapColumns() {
   return order.value
@@ -67,7 +68,7 @@ function mapColumns() {
 }
 
 function toggleColumnVisibility(
-  column: Column<unknown>,
+  column: Column<T>,
   visibility?: boolean | "indeterminate",
 ) {
   column.toggleVisibility(!!visibility);
@@ -78,7 +79,7 @@ const PIN_ICONS = {
   unpinned: "i-ph-push-pin",
 } as const;
 
-function togglePin(column: Column<unknown>) {
+function togglePin(column: Column<T>) {
   column.pin(column.getIsPinned() ? false : "left");
 }
 
@@ -98,11 +99,12 @@ const uiTableMenuColumn = computed(() => uiTableMenuColumnVariant());
 
 <template>
   <div :class="uiTableMenuColumn.root()">
-    <Draggable
-      v-model="columns"
+    <SortableList
+      :list="columns"
+      :item-key="columnKey"
       :class="uiTableMenuColumn.list()"
-      item-key="id"
       handle="#column-handler"
+      @update:list="applyColumnOrder"
     >
       <template #item="{ element: column }">
         <li :class="uiTableMenuColumn.item()">
@@ -145,7 +147,7 @@ const uiTableMenuColumn = computed(() => uiTableMenuColumnVariant());
           />
         </li>
       </template>
-    </Draggable>
+    </SortableList>
 
     <div :class="uiTableMenuColumn.actions()">
       <UButton

package/frontend-vue/layers/dms-ui/app/build/composables/block-preview/useBlockPreviewEmbed.ts

@@ -0,0 +1,123 @@
+import {
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+  type Ref,
+  type ShallowRef,
+} from "vue";
+import {
+  PREVIEW_THEMES,
+  parsePreviewMessage,
+  previewErrorMessage,
+  previewReadyMessage,
+  previewResizeMessage,
+  type PreviewInboundMessage,
+  type PreviewOutboundMessage,
+  type PreviewRenderMessage,
+  type PreviewState,
+  type PreviewTheme,
+  type PreviewThemeMessage,
+  type PreviewTree,
+} from "../../utils/blockPreview";
+
+/** What the embedded preview shows: `?state=` first, then each message. */
+export interface BlockPreviewEmbed {
+  tree: Ref<PreviewTree | undefined>;
+  /** Bumped on each `render`, so the blocks remount with fresh state. */
+  revision: Ref<number>;
+  /** Whether the page leaves its background to the embedding page. */
+  transparent: Ref<boolean>;
+  /** Tells the embedding page what went wrong. */
+  reportError: (message: string) => void;
+}
+
+interface EmbedOptions {
+  root: Readonly<ShallowRef<HTMLElement | null>>;
+  initialState: PreviewState | undefined;
+  setLocale: (locale: string) => void;
+}
+
+function postToParent(message: PreviewOutboundMessage): void {
+  if (window.parent === window) return;
+  // The preview is meant to be embedded by any docs site, and what it posts
+  // (a height, a ready flag, an error text) is not worth keeping from one.
+  window.parent.postMessage(message, "*");
+}
+
+/**
+ * Sets the class the color mode plugin keeps on `<html>`, without writing the
+ * visitor's stored preference: the theme belongs to the embedding page.
+ */
+function applyTheme(theme: PreviewTheme | undefined): void {
+  if (!theme || typeof document === "undefined") return;
+  const classes = document.documentElement.classList;
+  classes.remove(...PREVIEW_THEMES);
+  classes.add(theme);
+}
+
+function observeHeight(root: HTMLElement): ResizeObserver {
+  const observer = new ResizeObserver(() => {
+    postToParent(previewResizeMessage(root.getBoundingClientRect().height));
+  });
+  observer.observe(root);
+  return observer;
+}
+
+/**
+ * The embed side of `/dms-preview`: reads `render` and `theme` messages from
+ * the parent window, applies the theme and locale, and reports `ready`, each
+ * height change and errors back to it.
+ */
+export function useBlockPreviewEmbed(options: EmbedOptions): BlockPreviewEmbed {
+  const tree = ref<PreviewTree | undefined>(options.initialState?.tree);
+  const theme = ref(options.initialState?.theme);
+  const locale = ref(options.initialState?.locale);
+  const transparent = ref(options.initialState?.transparent ?? false);
+  const revision = ref(0);
+  let observer: ResizeObserver | undefined;
+
+  const handlers: Record<
+    PreviewInboundMessage["type"],
+    (message: PreviewInboundMessage) => void
+  > = {
+    render: (message) => {
+      const render = message as PreviewRenderMessage;
+      tree.value = render.tree;
+      theme.value = render.theme ?? theme.value;
+      locale.value = render.locale ?? locale.value;
+      transparent.value = render.transparent ?? transparent.value;
+      revision.value += 1;
+    },
+    theme: (message) => {
+      theme.value = (message as PreviewThemeMessage).theme;
+    },
+  };
+
+  function onMessage(event: MessageEvent): void {
+    if (event.source !== window.parent) return;
+    const message = parsePreviewMessage(event.data);
+    if (message) handlers[message.type](message);
+  }
+
+  watch(theme, applyTheme);
+  watch(locale, (next) => next && options.setLocale(next), { immediate: true });
+
+  onMounted(() => {
+    applyTheme(theme.value);
+    window.addEventListener("message", onMessage);
+    if (options.root.value) observer = observeHeight(options.root.value);
+    postToParent(previewReadyMessage());
+  });
+  onBeforeUnmount(() => {
+    window.removeEventListener("message", onMessage);
+    observer?.disconnect();
+  });
+
+  return {
+    tree,
+    revision,
+    transparent,
+    reportError: (message) => postToParent(previewErrorMessage(message)),
+  };
+}