mountly-vite-plugin 1.5.0 → 1.7.0

package/README.md

@@ -89,6 +89,19 @@ Pass `shadow: true` when the host is not one you trust: every element in the
 distribution then renders into its own shadow root, and the build emits one
 stylesheet that it injects into no document.
 
+Pass `peer: true` when one page loads several distributions, such as widgets
+from several teams. The build leaves the framework, its mountly adapter and
+mountly's runtime as bare imports (`react`, `mountly-react`, `mountly/embed`),
+and the page maps them once in an import map, so every distribution shares one
+React. Without it, each `embed.js` works alone on any page.
+
+`custom-elements.json` carries each component's JSDoc as its description, and
+each prop's JSDoc, its type as written (`"paid" | "overdue"`) and a JSON Schema
+derived from that type. JSDoc tags add constraints: `@minimum`, `@maximum`,
+`@minLength`, `@maxLength`, `@pattern` and `@format`. `@slot` tags declare the
+slots a component renders, and the element fills them from the page's children.
+Slots need a `shadow: true` distribution, and the build warns without one.
+
 See the [complete guide](https://mountly.dev/concepts/script-embeds/) and the
 [React](../../docs/examples/react-embed) and
 [mixed-framework](../../docs/examples/mixed-embed) examples.

package/dist/docs.d.ts

@@ -0,0 +1,31 @@
+import { type ExtractOptions } from "./props.js";
+/** A JSON Schema, as far as the build can derive one from a TypeScript type. */
+export type PropSchema = Record<string, unknown>;
+export interface ComponentDocs {
+    /** The component's JSDoc summary. */
+    description?: string;
+    /**
+     * Per prop: its JSDoc summary, its type as written (`"paid" | "overdue"`), and
+     * a JSON Schema derived from that type plus any `@minimum`, `@maximum`,
+     * `@minLength`, `@maxLength`, `@pattern` or `@format` tags.
+     */
+    props: Record<string, {
+        description?: string;
+        type?: string;
+        schema?: PropSchema;
+    }>;
+    /** `@slot` tags on the component: `@slot - body` or `@slot actions - the buttons`. */
+    slots?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+/**
+ * The prose a reader of the component's source would see: the JSDoc on the
+ * component and on each prop, and each prop's type as the author wrote it.
+ * The prop table says how to wire a prop; this says what it is for, which is
+ * what a person browsing a catalog — or a model composing from one — needs.
+ *
+ * Best effort: anything unreadable is simply absent, never an error.
+ */
+export declare function extractDocs(code: string, options?: ExtractOptions): ComponentDocs;

package/dist/embed.d.ts

@@ -1,5 +1,5 @@
 import { type UserConfig } from "vite";
-import type { MountlyWidgetFramework } from "./index.js";
+import { type MountlyWidgetFramework } from "./externals.js";
 import { type PropSpec } from "./props.js";
 export interface MountlyElementEntry {
     /** Browser-compatible component source, also importable directly by your app. */
@@ -42,6 +42,17 @@ export interface MountlyElementsConfigOptions {
      * of host you ship to, not the component.
      */
     shadow?: boolean;
+    /**
+     * Leave the framework (React, Vue or Svelte), its mountly adapter and
+     * mountly's runtime as bare imports, for the page's import map to resolve.
+     *
+     * Off by default, because then one script tag works on any page. Turn it on
+     * when one page loads several distributions — widgets from several teams,
+     * say — so they share one copy of React instead of each bringing its own.
+     * The page must map every bare specifier the build leaves behind (`react`,
+     * `react-dom/client`, `mountly-react`, `mountly/embed`, …).
+     */
+    peer?: boolean;
 }
 /**
  * Route each `new Worker(…)` that means the platform's Worker through the

package/dist/externals.d.ts

@@ -0,0 +1,11 @@
+/** Which imports a build leaves for the page to provide, per framework. */
+export type MountlyWidgetFramework = "react" | "vue" | "svelte";
+export declare function getFrameworkPeerExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
+/**
+ * The self-contained build's whole promise is "drop this file in a page and it
+ * works", so mountly's own runtime helpers are bundled in rather than
+ * externalised: the host then needs no import map at all. The peer build still
+ * externalises them, because sharing through the host's import map is the point
+ * of that build.
+ */
+export declare function getSelfContainedExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;

package/dist/index.d.ts

@@ -1,16 +1,8 @@
 import type { Plugin, UserConfig } from "vite";
 export { mountlyHostPlugin, type MountlyHostPluginOptions } from "./host.js";
 export { mountlyManifestFragmentPlugin, type ManifestFragmentPluginOptions } from "./fragment.js";
-export type MountlyWidgetFramework = "react" | "vue" | "svelte";
-export declare function getFrameworkPeerExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
-/**
- * The self-contained build's whole promise is "drop this file in a page and it
- * works", so mountly's own runtime helpers are bundled in rather than
- * externalised: the host then needs no import map at all. The peer build still
- * externalises them, because sharing through the host's import map is the point
- * of that build.
- */
-export declare function getSelfContainedExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
+import { getFrameworkPeerExternals, getSelfContainedExternals, type MountlyWidgetFramework } from "./externals.js";
+export { getFrameworkPeerExternals, getSelfContainedExternals, type MountlyWidgetFramework };
 export interface MountlyCssAsTextOptions {
     include?: string | RegExp | (string | RegExp)[];
 }
@@ -71,4 +63,5 @@ export interface DefineMountlyWidgetConfigOptions {
 }
 export declare function defineMountlyWidgetConfig(options?: DefineMountlyWidgetConfigOptions): UserConfig[];
 export { defineElementsConfig, type MountlyElementsConfigOptions, type MountlyElementEntry, } from "./embed.js";
+export { extractDocs, type ComponentDocs, type PropSchema } from "./docs.js";
 export { extractProps, type PropSpec, type PropKind } from "./props.js";

package/dist/index.js

@@ -592,9 +592,31 @@ ${JSON.stringify({ imports }, null, 2)}
   };
 }
 
+// src/externals.ts
+var PLATFORM_EXTERNALS = ["mountly", /^mountly\//];
+var FRAMEWORK_EXTERNALS = {
+  react: ["react", "react/jsx-runtime", "react-dom", "react-dom/client", "mountly-react"],
+  vue: ["vue", "mountly-vue"],
+  svelte: ["svelte", "mountly-svelte"]
+};
+var FRAMEWORK_BUNDLE = {
+  react: ["react", "react/jsx-runtime", "react-dom", "react-dom/client"],
+  vue: ["vue"],
+  svelte: ["svelte"]
+};
+function getFrameworkPeerExternals(framework) {
+  return [...PLATFORM_EXTERNALS, ...FRAMEWORK_EXTERNALS[framework]];
+}
+function getSelfContainedExternals(framework) {
+  return FRAMEWORK_EXTERNALS[framework].filter((id) => !FRAMEWORK_BUNDLE[framework].includes(id));
+}
+
 // src/embed.ts
 import { globSync, readFileSync as readFileSync2 } from "fs";
-import { basename, dirname as dirname3, extname, relative as relative3, resolve as resolve3 } from "path";
+import { basename, dirname as dirname4, extname, relative as relative3, resolve as resolve3 } from "path";
+import { parseAst as parseAst4 } from "vite";
+
+// src/docs.ts
 import { parseAst as parseAst2 } from "vite";
 
 // src/props.ts
@@ -906,6 +928,454 @@ function extractProps(code, options = {}) {
   return takesProps(declaration) === false ? [] : null;
 }
 
+// src/docs.ts
+function docBlock(source, start) {
+  const match = /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*$/.exec(source.slice(0, start));
+  if (!match) return { tags: [] };
+  const lines = (match[1] ?? "").split("\n").map((line) => line.replace(/^\s*\*? ?/, "").trim());
+  const joined = lines.join("\n").replace(/\s+@(?=[a-zA-Z])/g, "\n@");
+  const [prose = "", ...rest] = joined.split(/\n(?=@)/);
+  const tags = rest.map((tag) => {
+    const [, name2 = "", value = ""] = /^@(\w+)\s*([\s\S]*)$/.exec(tag.trim()) ?? [];
+    return [name2, value.replace(/\s+/g, " ").trim()];
+  });
+  const text = prose.trim();
+  return { ...text ? { text } : {}, tags };
+}
+var NUMERIC_TAGS = ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"];
+function constraints(tags) {
+  const out = {};
+  for (const [name2, value] of tags) {
+    if (NUMERIC_TAGS.includes(name2) && value !== "" && Number.isFinite(Number(value))) {
+      out[name2] = Number(value);
+    }
+    if (name2 === "pattern" || name2 === "format") out[name2] = value;
+  }
+  return out;
+}
+function schemaOf(type, types, source, depth = 0) {
+  if (!type || depth > 6) return {};
+  switch (type.type) {
+    case "TSStringKeyword":
+      return { type: "string" };
+    case "TSNumberKeyword":
+      return { type: "number" };
+    case "TSBooleanKeyword":
+      return { type: "boolean" };
+    case "TSNullKeyword":
+      return { type: "null" };
+    case "TSLiteralType": {
+      const value = type.literal?.value;
+      return value === void 0 ? {} : { const: value };
+    }
+    case "TSArrayType":
+      return { type: "array", items: schemaOf(type.elementType, types, source, depth + 1) };
+    case "TSParenthesizedType":
+      return schemaOf(type.typeAnnotation, types, source, depth);
+    case "TSUnionType": {
+      const parts = type.types.filter(
+        (t) => t.type !== "TSUndefinedKeyword" && t.type !== "TSNullKeyword"
+      );
+      if (parts.length === 1) return schemaOf(parts[0], types, source, depth);
+      const values = parts.map((t) => t.literal?.value);
+      if (parts.every((t) => t.type === "TSLiteralType") && values.every((v) => v !== void 0)) {
+        const kinds = new Set(values.map((v) => typeof v));
+        return kinds.size === 1 ? { type: [...kinds][0], enum: values } : { enum: values };
+      }
+      return { anyOf: parts.map((t) => schemaOf(t, types, source, depth + 1)) };
+    }
+    case "TSTypeLiteral":
+    case "TSInterfaceDeclaration":
+    case "TSIntersectionType":
+      return objectSchema(membersOf(type, types), types, source, depth);
+    case "TSTypeReference": {
+      const name2 = type.typeName?.name;
+      const args = type.typeArguments?.params ?? [];
+      if ((name2 === "Array" || name2 === "ReadonlyArray") && args[0]) {
+        return { type: "array", items: schemaOf(args[0], types, source, depth + 1) };
+      }
+      if (name2 === "Record" && args[1]) {
+        return {
+          type: "object",
+          additionalProperties: schemaOf(args[1], types, source, depth + 1)
+        };
+      }
+      const local = types.get(name2);
+      if (!local) return {};
+      return local.type === "TSInterfaceDeclaration" ? objectSchema(membersOf(local, types), types, source, depth) : schemaOf(local, types, source, depth + 1);
+    }
+    default:
+      return {};
+  }
+}
+function objectSchema(members, types, source, depth) {
+  if (!members) return { type: "object" };
+  const properties = {};
+  const required = [];
+  for (const member2 of members) {
+    if (member2.type !== "TSPropertySignature") continue;
+    const name2 = keyOf(member2);
+    if (!name2) continue;
+    const doc = docBlock(source, member2.start);
+    properties[name2] = {
+      ...schemaOf(member2.typeAnnotation?.typeAnnotation, types, source, depth + 1),
+      ...constraints(doc.tags),
+      ...doc.text ? { description: doc.text } : {}
+    };
+    if (!member2.optional) required.push(name2);
+  }
+  return {
+    type: "object",
+    properties,
+    ...required.length ? { required } : {},
+    additionalProperties: false
+  };
+}
+function statementOf(body, node) {
+  return body.find((s) => s.start <= node.start && node.start < s.end);
+}
+function htmlCommentBeforeScript(code) {
+  const match = /<!--((?:(?!-->)[\s\S])*?)-->\s*<script\b/.exec(code);
+  const text = match?.[1]?.trim();
+  return text || void 0;
+}
+function extractDocs(code, options = {}) {
+  try {
+    const file = options.file ?? "component.tsx";
+    const sfc = /\.(vue|svelte)$/.exec(file)?.[1];
+    const source = sfc ? scriptOf(code) : code;
+    const body = parseAst2(source, { lang: sfc ? "ts" : "tsx" }).body;
+    const types = localTypes(body);
+    let declared;
+    let description;
+    let component = { tags: [] };
+    if (sfc === "vue") {
+      const call = macroCall(body, "defineProps");
+      declared = call?.typeArguments?.params?.[0];
+      const statement = call && statementOf(body, call);
+      component = statement ? docBlock(source, statement.start) : component;
+      description = component.text ?? htmlCommentBeforeScript(code);
+    } else if (sfc === "svelte") {
+      const declarator = svelteProps(body);
+      declared = declarator?.id?.typeAnnotation?.typeAnnotation;
+      const statement = declarator && statementOf(body, declarator);
+      component = statement ? docBlock(source, statement.start) : component;
+      description = component.text ?? htmlCommentBeforeScript(code);
+    } else {
+      const declaration = findExport(body, options.exportName ?? "default");
+      if (declaration) {
+        const statement = statementOf(body, declaration);
+        const before = statement ? docBlock(source, statement.start) : { tags: [] };
+        component = before.text || before.tags.length ? before : docBlock(source, declaration.start);
+        description = component.text;
+        declared = propsType(declaration);
+      }
+    }
+    const props = {};
+    for (const member2 of membersOf(declared, types) ?? []) {
+      const name2 = keyOf(member2);
+      if (!name2) continue;
+      const annotation = member2.typeAnnotation?.typeAnnotation;
+      const doc = docBlock(source, member2.start);
+      const type = annotation ? source.slice(annotation.start, annotation.end) : void 0;
+      const schema = annotation ? { ...schemaOf(annotation, types, source), ...constraints(doc.tags) } : void 0;
+      props[name2] = {
+        ...doc.text ? { description: doc.text } : {},
+        ...type ? { type } : {},
+        ...schema && Object.keys(schema).length ? { schema } : {}
+      };
+    }
+    const slots = component.tags.filter(([tag]) => tag === "slot").map(([, value]) => {
+      const [, name2 = "", text = ""] = /^(?:([A-Za-z][\w-]*)\s*)?-?\s*([\s\S]*)$/.exec(value) ?? [];
+      return { name: name2, description: text.trim() };
+    });
+    return {
+      ...description ? { description } : {},
+      props,
+      ...slots.length ? { slots } : {}
+    };
+  } catch {
+    return { props: {} };
+  }
+}
+
+// src/types.ts
+import { dirname as dirname3, resolve as resolvePath } from "path";
+import { parseAst as parseAst3 } from "vite";
+function parseModule(file, code) {
+  const sfc = /\.(vue|svelte)$/.exec(file)?.[1];
+  const source = sfc ? scriptOf(code) : code;
+  const body = parseAst3(source, { lang: sfc ? "ts" : "tsx" }).body;
+  const mod = {
+    file,
+    source,
+    body,
+    types: /* @__PURE__ */ new Map(),
+    imports: /* @__PURE__ */ new Map(),
+    exports: /* @__PURE__ */ new Map(),
+    opaque: /* @__PURE__ */ new Set()
+  };
+  for (const raw of body) {
+    const node = raw.declaration ?? raw;
+    if (node.type === "TSInterfaceDeclaration" || node.type === "TSTypeAliasDeclaration") {
+      if (mod.types.has(node.id.name) || mod.opaque.has(node.id.name)) {
+        mod.types.delete(node.id.name);
+        mod.opaque.add(node.id.name);
+      } else {
+        mod.types.set(node.id.name, node);
+      }
+    } else if (node.type === "ImportDeclaration" || raw.source && raw.specifiers) {
+      for (const s of node.specifiers ?? []) {
+        if (s.type !== "ImportSpecifier" && s.type !== "ExportSpecifier") {
+          mod.opaque.add(s.local.name);
+          continue;
+        }
+        const name2 = s.imported ?? s.local;
+        const local = s.type === "ExportSpecifier" ? s.exported : s.local;
+        mod.imports.set(local.name ?? local.value, {
+          from: node.source.value,
+          name: name2.name ?? name2.value
+        });
+      }
+    } else if (raw.type === "ExportNamedDeclaration" && !raw.declaration) {
+      for (const s of raw.specifiers) {
+        mod.exports.set(s.exported.name ?? s.exported.value, s.local.name ?? s.local.value);
+      }
+    } else if (node.id?.name) {
+      mod.opaque.add(node.id.name);
+    }
+  }
+  const params = (node) => {
+    if (Array.isArray(node)) return node.forEach(params);
+    if (!node || typeof node !== "object") return;
+    const n = node;
+    if (n.type === "TSTypeParameter") mod.opaque.add(n.name.name);
+    for (const key in n) params(n[key]);
+  };
+  params(body);
+  for (const [, list = ""] of code.matchAll(/<script\b[^>]*\bgenerics?="([^"]*)"/g)) {
+    for (const part of list.split(",")) mod.opaque.add(part.trim().split(/\s/)[0] ?? "");
+  }
+  return mod;
+}
+function rewrite(source, node, edits) {
+  let out = source.slice(node.start, node.end);
+  for (const [start, end, text] of [...edits].sort((a, b) => b[0] - a[0])) {
+    out = out.slice(0, start - node.start) + text + out.slice(end - node.start);
+  }
+  return out;
+}
+function introduced(node) {
+  const names = (node.typeParameters?.params ?? []).map((p) => p.name.name);
+  if (node.type === "TSMappedType" && node.key?.name) names.push(node.key.name);
+  if (node.type === "TSConditionalType") {
+    const infer = (n) => {
+      if (Array.isArray(n)) return n.forEach(infer);
+      if (!n || typeof n !== "object") return;
+      if (n.type === "TSInferType") names.push(n.typeParameter.name.name);
+      for (const key in n) infer(n[key]);
+    };
+    infer(node.extendsType);
+  }
+  return names;
+}
+function tupleElement(node) {
+  if (!node || node.type === "TSRestType") return void 0;
+  if (node.type === "TSNamedTupleMember") {
+    if (node.elementType?.type === "TSRestType") return void 0;
+    const inner = node.elementType?.type === "TSOptionalType" ? node.elementType.typeAnnotation : node.elementType;
+    return { type: inner, optional: Boolean(node.optional) || inner !== node.elementType };
+  }
+  if (node.type === "TSOptionalType") return { type: node.typeAnnotation, optional: true };
+  return { type: node, optional: false };
+}
+var UTILITY_TYPES = /* @__PURE__ */ new Set([
+  "Array",
+  "ArrayLike",
+  "AsyncIterable",
+  "Awaited",
+  "Capitalize",
+  "ConstructorParameters",
+  "Exclude",
+  "Extract",
+  "InstanceType",
+  "Iterable",
+  "Lowercase",
+  "NoInfer",
+  "NonNullable",
+  "Omit",
+  "Parameters",
+  "Partial",
+  "Pick",
+  "PromiseLike",
+  "PropertyKey",
+  "Readonly",
+  "ReadonlyArray",
+  "ReadonlyMap",
+  "ReadonlySet",
+  "Record",
+  "Required",
+  "ReturnType",
+  "Uncapitalize",
+  "Uppercase"
+]);
+var NODE_ONLY = /* @__PURE__ */ new Set(["Buffer", "process", "global", "require", "module", "exports"]);
+function isGlobal(name2) {
+  if (UTILITY_TYPES.has(name2)) return true;
+  if (NODE_ONLY.has(name2)) return false;
+  if (/^(?:HTML|SVG)\w*Element$|^\w*Event(?:Init|Target)?$|^(?:Element|Node|Document|Window|ShadowRoot|DOMRect|FileList|DataTransfer|CSSStyleDeclaration|NodeList)$/.test(
+    name2
+  )) {
+    return true;
+  }
+  return name2 in globalThis;
+}
+function unwrap(type) {
+  if (type?.type === "TSParenthesizedType") return unwrap(type.typeAnnotation);
+  if (type?.type !== "TSUnionType") return type;
+  const real = type.types.filter(
+    (t) => t.type !== "TSUndefinedKeyword" && t.type !== "TSNullKeyword"
+  );
+  return real.length === 1 ? unwrap(real[0]) : type;
+}
+var CANDIDATES = ["", ".ts", ".tsx", ".d.ts", "/index.ts", "/index.tsx"];
+function embedTypes(code, options) {
+  const result = { props: {}, events: {}, declarations: [] };
+  const named = /* @__PURE__ */ new Map();
+  const taken = /* @__PURE__ */ new Set();
+  const modules = /* @__PURE__ */ new Map();
+  const load = (file) => {
+    if (!modules.has(file)) {
+      let mod = null;
+      try {
+        const text = options.load?.(file);
+        if (text !== void 0) mod = parseModule(file, text);
+      } catch {
+      }
+      modules.set(file, mod);
+    }
+    return modules.get(file) ?? null;
+  };
+  const resolve4 = (mod, name2, depth = 0) => {
+    const decl = mod.types.get(name2);
+    if (decl) return { decl, mod };
+    if (mod.opaque.has(name2) || depth > 8) return null;
+    const imp = mod.imports.get(name2);
+    if (!imp) return isGlobal(name2) ? void 0 : null;
+    if (!imp.from.startsWith(".")) return null;
+    const base = resolvePath(dirname3(mod.file), imp.from.replace(/\.[cm]?js$/, ""));
+    for (const ext of CANDIDATES) {
+      const other = load(base + ext);
+      if (other) return resolve4(other, other.exports.get(imp.name) ?? imp.name, depth + 1) ?? null;
+    }
+    return null;
+  };
+  const emit = (decl, mod) => {
+    const existing = named.get(decl);
+    if (existing) return existing;
+    let as = `${options.scope}_${decl.id.name}`;
+    for (let n = 2; taken.has(as); n++) as = `${options.scope}_${decl.id.name}${n}`;
+    named.set(decl, as);
+    taken.add(as);
+    const edits = [[decl.id.start, decl.id.end, as]];
+    if (!walk(decl, mod, /* @__PURE__ */ new Set(), edits)) return void 0;
+    result.declarations.push(`export ${rewrite(mod.source, decl, edits)}`);
+    return as;
+  };
+  const walk = (node, mod, scope, edits) => {
+    if (Array.isArray(node)) return node.every((n2) => walk(n2, mod, scope, edits));
+    if (!node || typeof node !== "object") return true;
+    const n = node;
+    if (n.type === "TSTypeQuery" || n.type === "TSImportType" || n.type === "TSQualifiedName" || n.type === "MemberExpression" || n.computed && n.key?.type !== "Literal") {
+      return false;
+    }
+    const own = introduced(n);
+    const inner = own.length ? /* @__PURE__ */ new Set([...scope, ...own]) : scope;
+    const ref = n.type === "TSTypeReference" ? n.typeName : n.type === "TSInterfaceHeritage" ? n.expression : null;
+    if (ref?.type === "Identifier" && !inner.has(ref.name)) {
+      const target = resolve4(mod, ref.name);
+      if (target === null) return false;
+      if (target) {
+        const as = emit(target.decl, target.mod);
+        if (!as) return false;
+        edits.push([ref.start, ref.end, as]);
+      }
+    }
+    for (const key in n) if (!walk(n[key], mod, inner, edits)) return false;
+    return true;
+  };
+  const typed = (node, mod) => {
+    if (!node) return void 0;
+    const mark = result.declarations.length;
+    const before = new Map(named);
+    const edits = [];
+    if (walk(node, mod, /* @__PURE__ */ new Set(), edits)) return rewrite(mod.source, node, edits);
+    result.declarations.length = mark;
+    named.clear();
+    taken.clear();
+    for (const [decl, as] of before) {
+      named.set(decl, as);
+      taken.add(as);
+    }
+    return void 0;
+  };
+  const detail = (params, mod, skip = 0) => {
+    const param = params?.[skip];
+    if (!param || param.type === "RestElement") return void 0;
+    const text = typed(param.typeAnnotation?.typeAnnotation, mod);
+    return text && param.optional ? `${text} | null` : text;
+  };
+  try {
+    const file = options.file ?? "component.tsx";
+    const mod = parseModule(file, code);
+    modules.set(file, mod);
+    const aliases = localTypes(mod.body);
+    const sfc = /\.(vue|svelte)$/.exec(file)?.[1];
+    let declared;
+    if (sfc === "vue") declared = macroCall(mod.body, "defineProps")?.typeArguments?.params?.[0];
+    else if (sfc === "svelte") declared = svelteProps(mod.body)?.id?.typeAnnotation?.typeAnnotation;
+    else {
+      const declaration = findExport(mod.body, options.exportName ?? "default");
+      declared = declaration ? propsType(declaration) : void 0;
+    }
+    for (const member2 of membersOf(declared, aliases) ?? []) {
+      const name2 = keyOf(member2);
+      if (!name2) continue;
+      if (/^on[A-Z]/.test(name2)) {
+        const fn = member2.type === "TSMethodSignature" ? member2 : unwrap(member2.typeAnnotation?.typeAnnotation);
+        if (fn?.type !== "TSFunctionType" && fn?.type !== "TSMethodSignature") continue;
+        if (fn.typeParameters) continue;
+        const text2 = detail(fn.params, mod);
+        if (text2) result.events[eventName(name2)] = text2;
+        continue;
+      }
+      if (member2.type !== "TSPropertySignature") continue;
+      const text = typed(member2.typeAnnotation?.typeAnnotation, mod);
+      if (text) result.props[name2] = text;
+    }
+    if (sfc === "vue") {
+      const emits = macroCall(mod.body, "defineEmits")?.typeArguments?.params?.[0];
+      for (const member2 of membersOf(emits, aliases) ?? []) {
+        if (member2.type === "TSPropertySignature") {
+          const event = keyOf(member2);
+          const tuple = member2.typeAnnotation?.typeAnnotation;
+          const first = tuple?.type === "TSTupleType" ? tuple.elementTypes[0] : void 0;
+          const element = tupleElement(first);
+          const text = element && typed(element.type, mod);
+          if (event && text) result.events[event] = element.optional ? `${text} | null` : text;
+        }
+        if (member2.type === "TSCallSignatureDeclaration") {
+          const event = member2.params?.[0]?.typeAnnotation?.typeAnnotation?.literal?.value;
+          const text = detail(member2.params, mod, 1);
+          if (typeof event === "string" && text) result.events[event] = text;
+        }
+      }
+    }
+  } catch {
+  }
+  return result;
+}
+
 // src/embed.ts
 function frameworkFor(file) {
   if (file.endsWith(".vue")) return "vue";
@@ -955,18 +1425,25 @@ function normalize(options, root) {
   return unique(entries);
 }
 function declarations(elements) {
-  const blocks = elements.map(({ tag, props }) => {
+  const blocks = elements.map(({ tag, props, types, docs }) => {
     const id = name(tag);
-    const members = props.filter((spec) => spec.kind !== "event").map((spec) => `  ${member(spec.name)}?: ${TS_TYPE[spec.kind] ?? "unknown"};`);
-    const events = props.filter((spec) => spec.kind === "event").map((spec) => `  ${JSON.stringify(spec.event)}: CustomEvent;`);
+    const members = props.filter((spec) => spec.kind !== "event").map(
+      (spec) => `${jsdoc(docs.props[spec.name]?.description, "  ")}  ${member(spec.name)}?: ${types.props[spec.name] ?? TS_TYPE[spec.kind] ?? "unknown"};`
+    );
+    const events = props.filter((spec) => spec.kind === "event").map((spec) => {
+      const detail = spec.event && types.events[spec.event];
+      return `${jsdoc(docs.props[spec.name]?.description, "  ")}  ${JSON.stringify(spec.event)}: CustomEvent${detail ? `<${detail}>` : ""};`;
+    });
     const block = (kind, lines) => lines.length ? `export interface ${id}${kind} {
 ${lines.join("\n")}
 }` : `export interface ${id}${kind} {}`;
-    return `${block("Props", members)}
+    return `${types.declarations.map((text) => `${text}
+
+`).join("")}${block("Props", members)}
 
 ${block("EventMap", events)}
 
-export interface ${id}Element extends MountlyElement<${id}Props> {
+${jsdoc(docs.description, "")}export interface ${id}Element extends MountlyElement<${id}Props> {
   addEventListener<K extends keyof ${id}EventMap>(
     type: K,
     listener: (this: ${id}Element, event: ${id}EventMap[K]) => unknown,
@@ -1032,6 +1509,16 @@ ${jsx.join("\n")}
 }
 `;
 }
+function jsdoc(text, indent) {
+  if (!text) return "";
+  const lines = text.replace(/\*\//g, "*\\/").split("\n");
+  if (lines.length === 1) return `${indent}/** ${lines[0]} */
+`;
+  return `${indent}/**
+${lines.map((line) => `${indent} *${line ? ` ${line}` : ""}`).join("\n")}
+${indent} */
+`;
+}
 function member(prop) {
   return /^[A-Za-z_$][\w$]*$/.test(prop) ? prop : JSON.stringify(prop);
 }
@@ -1043,36 +1530,53 @@ function manifest(elements) {
     {
       schemaVersion: "1.0.0",
       readme: "",
-      modules: elements.map(({ tag, entry, props }) => ({
-        kind: "javascript-module",
-        path: entry.component,
-        declarations: [
-          {
-            kind: "class",
-            name: name(tag),
-            customElement: true,
-            tagName: tag,
-            members: props.filter((spec) => spec.kind !== "event").map((spec) => ({
-              kind: "field",
-              name: spec.name,
-              type: { text: TS_TYPE[spec.kind] ?? "unknown" }
-            })),
-            attributes: props.filter((spec) => spec.attribute).map((spec) => ({
-              name: spec.attribute,
-              fieldName: spec.name,
-              type: { text: TS_TYPE[spec.kind] ?? "unknown" }
-            })),
-            events: props.filter((spec) => spec.kind === "event").map((spec) => ({ name: spec.event, type: { text: "CustomEvent" } }))
-          }
-        ],
-        exports: [
-          {
-            kind: "custom-element-definition",
-            name: tag,
-            declaration: { name: name(tag), module: entry.component }
-          }
-        ]
-      }))
+      modules: elements.map(({ tag, entry, props, docs }) => {
+        const cemType = (spec) => ({
+          text: docs.props[spec.name]?.type ?? TS_TYPE[spec.kind] ?? "unknown"
+        });
+        const described = (spec) => {
+          const { description, schema } = docs.props[spec.name] ?? {};
+          return { ...description ? { description } : {}, ...schema ? { schema } : {} };
+        };
+        return {
+          kind: "javascript-module",
+          path: entry.component,
+          declarations: [
+            {
+              kind: "class",
+              name: name(tag),
+              ...docs.description ? { description: docs.description } : {},
+              ...docs.slots ? { slots: docs.slots } : {},
+              customElement: true,
+              tagName: tag,
+              members: props.filter((spec) => spec.kind !== "event").map((spec) => ({
+                kind: "field",
+                name: spec.name,
+                type: cemType(spec),
+                ...described(spec)
+              })),
+              attributes: props.filter((spec) => spec.attribute).map((spec) => ({
+                name: spec.attribute,
+                fieldName: spec.name,
+                type: cemType(spec),
+                ...described(spec)
+              })),
+              events: props.filter((spec) => spec.kind === "event").map((spec) => ({
+                name: spec.event,
+                type: { text: "CustomEvent" },
+                ...described(spec)
+              }))
+            }
+          ],
+          exports: [
+            {
+              kind: "custom-element-definition",
+              name: tag,
+              declaration: { name: name(tag), module: entry.component }
+            }
+          ]
+        };
+      })
     },
     null,
     2
@@ -1126,7 +1630,7 @@ function resolveCssToken(bundle) {
       output.code = output.code.replace(token, "void 0");
       continue;
     }
-    const href = relative3(dirname3(output.fileName), stylesheet).replace(/\\/g, "/");
+    const href = relative3(dirname4(output.fileName), stylesheet).replace(/\\/g, "/");
     output.code = output.code.replace(
       token,
       `new URL(${JSON.stringify(`./${href}`)}, import.meta.url).href`
@@ -1234,7 +1738,7 @@ function shimWorkers(code) {
       walk(child, node, outside ? shadowed : hidden);
     }
   };
-  walk(parseAst2(code, { lang: "js" }), void 0, false);
+  walk(parseAst4(code, { lang: "js" }), void 0, false);
   if (!callees.length) return null;
   let out = code;
   for (const { start, end } of callees.sort((a, b) => b.start - a.start)) {
@@ -1242,18 +1746,61 @@ function shimWorkers(code) {
   }
   return WORKER_SHIM + out;
 }
-function readPropTable(entry, tag, root) {
-  const file = resolve3(root, entry.component);
-  const props = extractProps(readFileSync2(file, "utf8"), {
-    file,
-    exportName: entry.exportName
-  });
+var NATIVE_BUBBLING = /* @__PURE__ */ new Set([
+  "click",
+  "dblclick",
+  "input",
+  "change",
+  "submit",
+  "reset",
+  "select",
+  "keydown",
+  "keyup",
+  "focusin",
+  "focusout",
+  "pointerdown",
+  "pointerup",
+  "mousedown",
+  "mouseup",
+  "contextmenu",
+  "wheel",
+  "beforeinput",
+  "invalid"
+]);
+function warnNativeEvents(elements, warn) {
+  for (const { tag, props } of elements) {
+    for (const spec of props) {
+      if (spec.kind === "event" && spec.event && NATIVE_BUBBLING.has(spec.event)) {
+        warn(
+          `[mountly] <${tag}> ${spec.name} dispatches "${spec.event}", which is also a native event bubbling out of the component. Listeners will get both. Rename the prop (e.g. ${spec.name}Item) so its event is unambiguous.`
+        );
+      }
+    }
+  }
+}
+function readElementSource(entry, tag, root) {
+  const source = readFileSync2(resolve3(root, entry.component), "utf8");
+  const opts = { file: entry.component, exportName: entry.exportName };
+  const props = entry.props ?? extractProps(source, opts);
   if (!props) {
     throw new Error(
       `[mountly] cannot read the props of ${entry.component} for <${tag}>. Declare the props type in that file, or pass \`props\` on the element entry.`
     );
   }
-  return props;
+  const docs = extractDocs(source, opts);
+  const types = entry.props ? { props: {}, events: {}, declarations: [] } : embedTypes(source, {
+    ...opts,
+    file: resolve3(root, entry.component),
+    scope: name(tag),
+    load: (file) => {
+      try {
+        return readFileSync2(file, "utf8");
+      } catch {
+        return void 0;
+      }
+    }
+  });
+  return { props, docs, types };
 }
 function defineElementsConfig(options) {
   const entryId = "virtual:mountly-embed";
@@ -1269,12 +1816,26 @@ function defineElementsConfig(options) {
     configResolved(config) {
       root = config.root;
       assertSingleCompiler(config.plugins);
-      elements = normalize(options, root).map(([tag, entry]) => ({
-        tag,
-        entry,
-        props: entry.props ?? readPropTable(entry, tag, root),
-        framework: entry.framework ?? frameworkFor(entry.component)
-      }));
+      elements = normalize(options, root).map(([tag, entry]) => {
+        const { props, docs, types } = readElementSource(entry, tag, root);
+        return {
+          tag,
+          entry,
+          props,
+          framework: entry.framework ?? frameworkFor(entry.component),
+          docs,
+          types
+        };
+      });
+      const warn = config.logger?.warn.bind(config.logger) ?? console.warn;
+      warnNativeEvents(elements, warn);
+      if (!shadow) {
+        for (const { tag } of elements.filter((element) => element.docs.slots)) {
+          warn(
+            `[mountly] <${tag}> declares @slot, but slots project only in a shadow root. Build the distribution with \`shadow: true\`, or the page's children render after the component instead of inside it.`
+          );
+        }
+      }
     },
     resolveId(id) {
       if (id === entryId || id.startsWith(widgetPrefix)) return `\0${id}`;
@@ -1282,10 +1843,11 @@ function defineElementsConfig(options) {
     load(id) {
       if (id === `\0${entryId}`) {
         const definitions = elements.map(
-          ({ tag, entry, props }) => `${JSON.stringify(tag)}: {
+          ({ tag, entry, props, docs }) => `${JSON.stringify(tag)}: {
     load: () => import(${JSON.stringify(widgetPrefix + tag)}),
     props: ${JSON.stringify(props)},
-    trigger: ${JSON.stringify(entry.trigger ?? "connected")}
+    trigger: ${JSON.stringify(entry.trigger ?? "connected")}${docs.slots ? `,
+    slots: ${JSON.stringify(docs.slots.map((slot) => slot.name))}` : ""}
   }`
         );
         return `import { defineElements } from "mountly/embed";
@@ -1358,6 +1920,18 @@ export default createWidget(component[${JSON.stringify(element.entry.exportName
       // stylesheet nothing injects, which each element adopts for itself.
       cssCodeSplit: !shadow,
       rollupOptions: {
+        ...options.peer ? {
+          external: [
+            ...new Set(
+              [...frameworks].flatMap((framework) => [
+                ...getFrameworkPeerExternals(framework),
+                // Compiled Svelte imports `svelte/internal/client`; bundling it
+                // beside an external `svelte` would mean two runtimes.
+                ...framework === "svelte" ? [/^svelte\//] : []
+              ])
+            )
+          ]
+        } : {},
         input: entryId,
         output: { entryFileNames: "embed.js", chunkFileNames: "assets/[name]-[hash].js" }
       }
@@ -1366,23 +1940,6 @@ export default createWidget(component[${JSON.stringify(element.entry.exportName
 }
 
 // src/index.ts
-var PLATFORM_EXTERNALS = ["mountly", /^mountly\//];
-var FRAMEWORK_EXTERNALS = {
-  react: ["react", "react/jsx-runtime", "react-dom", "react-dom/client", "mountly-react"],
-  vue: ["vue", "mountly-vue"],
-  svelte: ["svelte", "mountly-svelte"]
-};
-var FRAMEWORK_BUNDLE = {
-  react: ["react", "react/jsx-runtime", "react-dom", "react-dom/client"],
-  vue: ["vue"],
-  svelte: ["svelte"]
-};
-function getFrameworkPeerExternals(framework) {
-  return [...PLATFORM_EXTERNALS, ...FRAMEWORK_EXTERNALS[framework]];
-}
-function getSelfContainedExternals(framework) {
-  return FRAMEWORK_EXTERNALS[framework].filter((id) => !FRAMEWORK_BUNDLE[framework].includes(id));
-}
 function matchesFilter(id, include) {
   return include.some(
     (pattern) => typeof pattern === "string" ? id.includes(pattern) : pattern.test(id)
@@ -1556,6 +2113,7 @@ function defineMountlyWidgetConfig(options = {}) {
 export {
   defineElementsConfig,
   defineMountlyWidgetConfig,
+  extractDocs,
   extractProps,
   getFrameworkPeerExternals,
   getSelfContainedExternals,

package/dist/props.d.ts

@@ -20,6 +20,26 @@ export interface PropSpec {
 export declare function kebab(name: string): string;
 /** `onViewDetails` → `view-details`. */
 export declare function eventName(prop: string): string;
+export type Node = Record<string, any>;
+/** Local `interface`/`type` declarations, so a `Props` reference can be resolved. */
+export declare function localTypes(body: Node[]): Map<string, Node>;
+/** The members of a type literal, an interface (with its bases), or a reference. */
+export declare function membersOf(type: Node | undefined, types: Map<string, Node>, seen?: number): Node[] | null;
+/** Find the declaration a build entry points at: `default`, or a named export. */
+export declare function findExport(body: Node[], exportName: string): Node | null;
+export declare function propsType(declaration: Node): Node | undefined;
+/** The `<script>` halves of an SFC, which is where all the types live. */
+export declare function scriptOf(code: string): string;
+/** `label` or `'aria-label'` — both name a prop. */
+export declare function keyOf(node: Node): string | null;
+/**
+ * `defineProps<T>()` / `defineEmits<T>()`, wherever it sits — including inside
+ * `withDefaults(defineProps<T>(), { … })`, which is how a Vue component with
+ * default values is normally written.
+ */
+export declare function macroCall(body: Node[], macro: string): Node | undefined;
+/** Svelte 5: `let { … }: Props = $props()`. */
+export declare function svelteProps(body: Node[]): Node | null;
 export interface ExtractOptions {
     /** Path or filename. Its extension selects the component dialect. */
     file?: string;

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+import { type ExtractOptions } from "./props.js";
+export interface EmbedTypes {
+    /** Per prop, its type as written, with copied names renamed. */
+    props: Record<string, string>;
+    /** Per DOM event, the type of its `detail`: the callback's first argument. */
+    events: Record<string, string>;
+    /** The declarations those types name, to emit beside them. */
+    declarations: string[];
+}
+export interface EmbedTypesOptions extends ExtractOptions {
+    /** Prefix for copied declarations, so two elements' `Line` types cannot collide. */
+    scope: string;
+    /** Read a file an import points at. Absent or `undefined`: imports stay opaque. */
+    load?: (file: string) => string | undefined;
+}
+export declare function embedTypes(code: string, options: EmbedTypesOptions): EmbedTypes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mountly-vite-plugin",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Vite lib build plugin for mountly vertical widgets (dual ESM output)",
   "license": "Apache-2.0",
   "repository": {