@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/handles/MetaTags.tsx

@@ -8,6 +8,10 @@
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
+ * This makes MetaTags the sole FOUC-script injector for apps that render it;
+ * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
+ * Rendering both is safe (the inline script guards listener registration) but
+ * redundant.
  *
  * @example
  * ```tsx
@@ -27,10 +31,12 @@
 import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
+import { isThenable } from "./is-thenable.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
 import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeJsonForScript } from "../escape-script.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -91,30 +97,27 @@ function hasTagName(
 }
 
 /**
- * Check if a value is a Promise.
+ * Check if a value is a Promise. Uses the shared thenable predicate (callable
+ * `then`) so collect (meta.ts) and render never disagree: an object carrying a
+ * non-callable `then` (e.g. `{ then: 5 }`) is a SYNC descriptor on both sides,
+ * not a Promise that would crash React's `use()`.
  */
 function isPromise(value: unknown): value is Promise<unknown> {
-  return value !== null && typeof value === "object" && "then" in value;
+  return isThenable(value);
 }
 
-/**
- * Render a single meta descriptor as a React element.
- */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
-  // charset
   if (hasCharSet(descriptor)) {
     return <meta key="charSet" charSet={descriptor.charSet} />;
   }
 
-  // title
   if (hasTitle(descriptor)) {
     return <title key="title">{descriptor.title}</title>;
   }
 
-  // name + content (description, viewport, etc.)
   if (hasNameContent(descriptor)) {
     return (
       <meta
@@ -125,7 +128,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +138,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,9 +148,10 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   if (hasScriptLdJson(descriptor)) {
-    const json = JSON.stringify(descriptor["script:ld+json"]);
+    const json = escapeJsonForScript(
+      JSON.stringify(descriptor["script:ld+json"]),
+    );
     return (
       <script
         key={`ld-json-${index}`}
@@ -159,7 +161,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // Custom tagName (meta or link with arbitrary attributes)
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
@@ -180,7 +181,6 @@ function renderMetaDescriptor(
     }
   }
 
-  // Fallback: treat as meta attributes
   return (
     <meta
       key={`meta-fallback-${index}`}
@@ -189,17 +189,54 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
-function AsyncMetaTag({
+// Sentinel a rejected async descriptor resolves to: renderMetaDescriptor sees
+// no recognized fields and returns nothing renderable (see renderRejected).
+const REJECTED_META: unique symbol = Symbol("rango.rejectedMeta");
+
+// Cache the rejection-swallowing wrapper per source promise so use() gets a
+// stable reference across re-renders (a fresh .then() each render would make
+// React treat it as a new pending promise and never settle). WeakMap keys on
+// the original promise so entries are collected with it.
+const safeMetaPromises = new WeakMap<
+  Promise<MetaDescriptorBase>,
+  Promise<MetaDescriptorBase | typeof REJECTED_META>
+>();
+
+function toSafeMetaPromise(
+  promise: Promise<MetaDescriptorBase>,
+): Promise<MetaDescriptorBase | typeof REJECTED_META> {
+  let safe = safeMetaPromises.get(promise);
+  if (!safe) {
+    // Swallow the rejection at the promise boundary, not via an error boundary:
+    // an error boundary above a suspended use() makes React abandon the whole
+    // Suspense subtree (and on the server switch it to client rendering). A
+    // settled-to-sentinel promise degrades the single bad descriptor to nothing
+    // while every sibling descriptor still renders.
+    //
+    // Normalize via Promise.resolve first: a collected async descriptor may be a
+    // non-native thenable (a React wakeable in SSR/RSC) whose .then() returns
+    // void rather than a Promise. Calling .then directly would leave `safe`
+    // undefined and use(undefined) would throw ("unsupported type passed to
+    // use()"), 500-ing the page. Promise.resolve adopts the thenable into a
+    // native Promise whose .then always returns one.
+    safe = Promise.resolve(promise).then(
+      (value) => value,
+      () => REJECTED_META,
+    );
+    safeMetaPromises.set(promise, safe);
+  }
+  return safe;
+}
+
+export function AsyncMetaTag({
   promise,
   index,
 }: {
   promise: Promise<MetaDescriptorBase>;
   index: number;
 }): React.ReactNode {
-  const resolved = use(promise);
+  const resolved = use(toSafeMetaPromise(promise));
+  if (resolved === REJECTED_META) return null;
   return renderMetaDescriptor(resolved, index);
 }
 
@@ -230,6 +267,12 @@ export function MetaTags(): React.ReactNode {
         />
       )}
       {descriptors.map((descriptor, index) => {
+        // A descriptor is only a Promise on the SSR/hydration path, where it is
+        // use()d to stream the tag into the document. On client navigation the
+        // store resolves deferred handle values before applying them (see
+        // processHandles), so MetaTags only ever receives resolved descriptors
+        // there and never suspends — which would otherwise revert the committed
+        // route (MetaTags lives in <head>, above the route's <Suspense>).
         if (isPromise(descriptor)) {
           return (
             <AsyncMetaTag

package/src/handles/Scripts.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+/**
+ * Renders the scripts collected by the Script handle into the document.
+ *
+ * Place `<Scripts />` inside `<head>` (default) and, if you push body scripts,
+ * `<Scripts position="body" />` at the top of `<body>`. Each site renders the
+ * configs whose `position` matches; the request CSP nonce is applied
+ * automatically to every DOCUMENT-RENDERED <script> (consumers never pass it). An
+ * async script first encountered on a soft navigation is injected client-side
+ * where the nonce is unavailable, so it carries no nonce and relies on
+ * 'strict-dynamic' (or a host allowance) — see the nonce caveat in the /scripts
+ * skill.
+ *
+ * EXECUTION CONTRACT — see the Script handle's docs. Inline + ordered (defer)
+ * scripts are document-load: they execute only when present in the initial HTML,
+ * so this component FREEZES that set after hydration (the initializer below runs
+ * once) — a later soft navigation never inserts an inert <script> (React creates
+ * client-mounted scripts via innerHTML, which the HTML spec makes non-executing).
+ * Async external scripts are React resources and stay reactive: React loads them
+ * on first encounter, including after navigation, deduped by src.
+ *
+ * @example
+ * ```tsx
+ * <html>
+ *   <head>
+ *     <MetaTags />
+ *     <Scripts />
+ *   </head>
+ *   <body>
+ *     <Scripts position="body" />
+ *     {children}
+ *   </body>
+ * </html>
+ * ```
+ */
+
+import { useState, type ReactNode } from "react";
+import { useHandle } from "../browser/react/use-handle.js";
+import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeScriptBody } from "../escape-script.js";
+import { Script, type ScriptAttributes, type ScriptConfig } from "./script.js";
+
+/** An external async script is a React-managed resource (reactive on nav). */
+function isAsyncResource(config: ScriptConfig): boolean {
+  return config.src != null && config.async === true;
+}
+
+// Fields the Script handle owns (set via the ScriptConfig fields, applied as
+// explicit props by renderScript) plus the inline-content props. Dropped from the
+// attributes bag so untyped/serialized input cannot smuggle them in — e.g.
+// `children`/`dangerouslySetInnerHTML` alongside an inline body makes React throw,
+// or `src` on an inline script. The discriminated type already excludes these;
+// this is the runtime guard.
+const MANAGED_ATTRS = new Set([
+  "id",
+  "src",
+  "async",
+  "defer",
+  "type",
+  "children",
+  "nonce",
+  "dangerouslySetInnerHTML",
+]);
+
+// Drop managed fields + any `on*` event handlers (a config serializes across the
+// server -> client boundary, so a function cannot survive it) from the passthrough
+// attributes, warning in dev.
+function passthroughAttributes(
+  attributes: ScriptAttributes | undefined,
+): Record<string, unknown> {
+  if (!attributes) return {};
+  const out: Record<string, unknown> = {};
+  const dev = process.env.NODE_ENV !== "production";
+  for (const [key, value] of Object.entries(
+    attributes as Record<string, unknown>,
+  )) {
+    const isHandler = key.startsWith("on");
+    if (isHandler || MANAGED_ATTRS.has(key)) {
+      if (dev) {
+        console.warn(
+          isHandler
+            ? `[Scripts] event handler "${key}" in a script's attributes is ` +
+                `dropped; callbacks cannot cross the server -> client handle ` +
+                `boundary. Use a "use client" component for load/error handling.`
+            : `[Scripts] managed field "${key}" in a script's attributes is ` +
+                `dropped; set it via the ScriptConfig fields (the request nonce ` +
+                `is applied automatically).`,
+        );
+      }
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function renderScript(
+  config: ScriptConfig,
+  nonce: string | undefined,
+  index: number,
+): ReactNode {
+  const { id, src, children, async, defer, type, attributes } = config;
+  const key = id ?? src ?? `rango-script-${index}`;
+  const attrs = passthroughAttributes(attributes);
+
+  // Inline: rendered in place (never hoisted), escaped against </script> breakout.
+  // The server-only nonce makes the attribute differ from the (undefined) client
+  // value, so suppressHydrationWarning is required — the same sanctioned pattern
+  // as the theme/Meta inline scripts.
+  if (src == null) {
+    if (children == null) return null;
+    return (
+      <script
+        key={key}
+        {...attrs}
+        id={id}
+        type={type}
+        nonce={nonce}
+        suppressHydrationWarning
+        dangerouslySetInnerHTML={{ __html: escapeScriptBody(children) }}
+      />
+    );
+  }
+
+  if (
+    process.env.NODE_ENV !== "production" &&
+    config.position === "body" &&
+    async
+  ) {
+    console.warn(
+      `[Scripts] An async external script (src="${src}") is hoisted into ` +
+        `<head> by React; position: "body" is ignored for it.`,
+    );
+  }
+
+  // External: async => React-hoisted, src-deduped resource; otherwise in place
+  // (defer or plain), preserving authoring order.
+  return (
+    <script
+      key={key}
+      {...attrs}
+      id={id}
+      type={type}
+      src={src}
+      async={async}
+      defer={defer}
+      nonce={nonce}
+      suppressHydrationWarning
+    />
+  );
+}
+
+export function Scripts({
+  position = "head",
+}: { position?: "head" | "body" } = {}): ReactNode {
+  const all = useHandle(Script) as ScriptConfig[];
+  const nonce = useNonce();
+
+  const forPosition = all.filter(
+    (config) => (config.position ?? "head") === position,
+  );
+
+  // Document-load scripts (inline + ordered external) execute only from the
+  // initial HTML, so freeze them to the first-render set. The initializer runs
+  // during SSR and again at hydration with the same handle data, so the output
+  // matches; afterwards a navigation cannot add an inert <script>.
+  const [documentLoad] = useState(() =>
+    forPosition.filter((config) => !isAsyncResource(config)),
+  );
+  // Async external scripts are resources React loads on first encounter; keep
+  // them reactive so a script first reached via navigation still loads.
+  const asyncResources = forPosition.filter(isAsyncResource);
+
+  return (
+    <>
+      {documentLoad.map((config, index) => renderScript(config, nonce, index))}
+      {asyncResources.map((config, index) =>
+        renderScript(config, nonce, index),
+      )}
+    </>
+  );
+}

package/src/handles/breadcrumbs.ts

@@ -3,7 +3,8 @@
  *
  * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
  * Items are collected in parent-to-child order with automatic deduplication
- * by `href` (last item for each href wins).
+ * by `href`: each href keeps its FIRST position but takes the LAST value, so a
+ * child re-pushing a parent href refreshes the label without reordering the trail.
  *
  * @example
  * ```tsx
@@ -22,6 +23,7 @@
 
 import type { ReactNode } from "react";
 import { createHandle, type Handle } from "../handle.js";
+import { isThenable } from "./is-thenable.js";
 
 /**
  * A single breadcrumb item.
@@ -38,19 +40,46 @@ export interface BreadcrumbItem {
 
 /**
  * Collect function for Breadcrumbs handle.
- * Flattens segments in parent-to-child order with deduplication by href
- * (last item for each href wins).
+ * Flattens segments in parent-to-child order with deduplication by href: each
+ * href keeps its FIRST position but takes the LAST value (re-pushing a parent
+ * href refreshes the label in place without reordering the trail).
+ * Deferred slots (`ctx.use(Breadcrumbs).defer()`)
+ * arrive as pending Promise entries with no href yet; they are passed through by
+ * identity and excluded from the href dedup so concurrent deferred crumbs do not
+ * all collapse under a single `undefined` href.
  */
 function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const all = segments.flat();
-  const seen = new Map<string, number>();
 
-  for (let i = 0; i < all.length; i++) {
-    seen.set(all[i].href, i);
+  const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
+    item != null &&
+    typeof item === "object" &&
+    !isThenable(item) &&
+    typeof (item as { href?: unknown }).href === "string";
+
+  // Dedup resolved crumbs by href: keep the FIRST position (preserving
+  // parent->child order) but the LAST value (a child re-pushing a parent's href
+  // can refresh its label). Deferred items bypass dedup entirely (they have no
+  // href yet) and are passed through by identity at their original position.
+  const valueByHref = new Map<string, BreadcrumbItem>();
+  for (const item of all) {
+    if (isResolvedItem(item)) valueByHref.set(item.href, item);
   }
 
-  // Return items in order, keeping only the last occurrence per href
-  return all.filter((item, index) => seen.get(item.href) === index);
+  const result: BreadcrumbItem[] = [];
+  const emitted = new Set<string>();
+  for (const item of all) {
+    if (!isResolvedItem(item)) {
+      result.push(item);
+      continue;
+    }
+    // Emit each href once, at its first occurrence, with the final value.
+    if (!emitted.has(item.href)) {
+      emitted.add(item.href);
+      result.push(valueByHref.get(item.href)!);
+    }
+  }
+  return result;
 }
 
 /**

package/src/handles/is-thenable.ts

@@ -0,0 +1,19 @@
+/**
+ * Single thenable predicate shared by the built-in handles that distinguish a
+ * synchronous descriptor/item from a deferred `Promise` one (Meta collect, the
+ * MetaTags render side, and Breadcrumbs).
+ *
+ * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
+ * `"then" in obj` membership check. The two had drifted: a descriptor carrying a
+ * non-callable `then` (e.g. a serialized shape `{ then: 5 }`) was classified as
+ * synchronous by collect but as a Promise by render — so render would call
+ * React's `use()` on a non-thenable and throw. One owner keeps the collect and
+ * render sides from ever disagreeing.
+ */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}

package/src/handles/meta.ts

@@ -29,15 +29,20 @@
  */
 
 import { createHandle, type Handle } from "../handle.js";
+import { isThenable } from "./is-thenable.js";
 import type {
   MetaDescriptor,
+  MetaDescriptorBase,
   TitleDescriptor,
   UnsetDescriptor,
 } from "../router/types.js";
 
-/**
- * Type guard for unset descriptor
- */
+function isPromiseDescriptor(
+  descriptor: MetaDescriptor,
+): descriptor is Promise<MetaDescriptorBase> {
+  return isThenable(descriptor);
+}
+
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -49,9 +54,6 @@ function isUnsetDescriptor(
   );
 }
 
-/**
- * Type guard for title descriptor (any form)
- */
 function isTitleDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
@@ -62,9 +64,6 @@ function isTitleDescriptor(
   );
 }
 
-/**
- * Type guard for title template descriptor
- */
 function isTitleTemplate(
   title: TitleDescriptor,
 ): title is { template: string; default: string } {
@@ -76,21 +75,13 @@ function isTitleTemplate(
   );
 }
 
-/**
- * Type guard for absolute title descriptor
- */
 function isAbsoluteTitle(
   title: TitleDescriptor,
 ): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
-/**
- * Get a unique key for a meta descriptor for deduplication.
- * Returns undefined for descriptors that shouldn't be deduplicated.
- */
 function getMetaKey(descriptor: MetaDescriptor): string | undefined {
-  // Skip unset descriptors - they are processed separately
   if (isUnsetDescriptor(descriptor)) {
     return undefined;
   }
@@ -110,13 +101,10 @@ function getMetaKey(descriptor: MetaDescriptor): string | undefined {
     return `httpEquiv:${descriptor.httpEquiv}`;
   }
   if ("script:ld+json" in descriptor) {
-    // JSON-LD scripts can have multiple, don't dedupe by default
     return undefined;
   }
   if ("tagName" in descriptor) {
-    // For link tags, dedupe by rel if present
     if (descriptor.tagName === "link" && "rel" in descriptor) {
-      // Some link rels should be unique (canonical), others not (stylesheet)
       const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
       if (uniqueRels.includes(descriptor.rel as string)) {
         return `link:${descriptor.rel}`;
@@ -136,9 +124,6 @@ const defaultMetaDescriptors: MetaDescriptor[] = [
   { name: "viewport", content: "width=device-width, initial-scale=1" },
 ];
 
-/**
- * Helper to add or replace a descriptor in the result array
- */
 function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
@@ -155,9 +140,6 @@ function addOrReplace(
   }
 }
 
-/**
- * Helper to update indices after removing an element
- */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
   removedIndex: number,
@@ -169,17 +151,11 @@ function updateIndicesAfterRemoval(
   }
 }
 
-/**
- * Collect function for Meta handle.
- * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
- * Supports title templates, absolute titles, and unset descriptors.
- */
 function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
   const result: MetaDescriptor[] = [];
   const keyToIndex = new Map<string, number>();
   let titleTemplate: string | undefined;
 
-  // Add defaults first so they can be overridden
   for (const descriptor of defaultMetaDescriptors) {
     const key = getMetaKey(descriptor);
     if (key !== undefined) {
@@ -190,7 +166,37 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Handle unset descriptors
+      // Promise descriptors cannot be inspected synchronously (their content is
+      // unknown until resolved in <MetaTags> via React's use()), so they bypass
+      // key-based dedup and title-templating: they are appended verbatim. Warn in
+      // dev when a title template is active so the author knows an async
+      // descriptor will NOT participate in the template/dedup.
+      //
+      // The warning is deliberately a GENERAL note, not a duplicate-<title>
+      // prediction: collectMeta cannot tell whether this Promise resolves to a
+      // title (which would indeed yield a 2nd <title>) or to an ordinary
+      // descriptor like an async og:image (which would not). Asserting a
+      // duplicate <title> here is a false positive for the common og:image case,
+      // so the message states only that async descriptors bypass templating —
+      // not that a duplicate <title> WILL occur.
+      if (isPromiseDescriptor(descriptor)) {
+        if (
+          titleTemplate !== undefined &&
+          process.env.NODE_ENV !== "production"
+        ) {
+          console.warn(
+            `[Meta] A Promise meta descriptor was pushed while a title template is active. ` +
+              `Async descriptors bypass deduplication and title-templating: the template is ` +
+              `not applied to them. If this Promise resolves to a title, resolve the value ` +
+              `before pushing (or push a synchronous descriptor) so it participates in the ` +
+              `template; if it resolves to a non-title descriptor (e.g. og:image), this ` +
+              `note does not apply.`,
+          );
+        }
+        result.push(descriptor);
+        continue;
+      }
+
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -202,14 +208,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle title descriptors with template/absolute support
       if (isTitleDescriptor(descriptor)) {
         const titleValue = descriptor.title;
 
         if (isTitleTemplate(titleValue)) {
-          // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
-          // Set the default title
           addOrReplace(
             result,
             keyToIndex,
@@ -220,7 +223,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         }
 
         if (isAbsoluteTitle(titleValue)) {
-          // Absolute title bypasses any template
           addOrReplace(
             result,
             keyToIndex,
@@ -230,9 +232,12 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           continue;
         }
 
-        // String title - apply template if one exists
+        // Insert the title literally. String.prototype.replace treats the
+        // replacement string specially ($&, $`, $', $$, $n), so a title like
+        // "Save $5" or one containing "$&" would be mangled. split/join inserts
+        // the raw value with no special-character interpretation.
         const finalTitle = titleTemplate
-          ? titleTemplate.replace("%s", titleValue as string)
+          ? titleTemplate.split("%s").join(titleValue as string)
           : titleValue;
         addOrReplace(
           result,
@@ -243,7 +248,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle all other descriptors
       const key = getMetaKey(descriptor);
       addOrReplace(result, keyToIndex, descriptor, key);
     }
@@ -257,6 +261,13 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  *
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
+ *
+ * Deduplication and title-templating apply only to SYNCHRONOUS descriptors.
+ * A Promise descriptor (`Promise<MetaDescriptorBase>`) is appended verbatim —
+ * its content is not known until it resolves in `<MetaTags>`, so it cannot be
+ * keyed for dedup nor receive a parent title template. If you need a child title
+ * to participate in a layout's `%s` template, push the resolved string title
+ * synchronously rather than a `Promise<{ title }>`.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,