@backstage/plugin-techdocs-react 0.0.0-nightly-20260928023907 → 0.0.0-nightly-20261027023041

package/CHANGELOG.md

@@ -1,17 +1,56 @@
 # @backstage/plugin-techdocs-react
 
-## 0.0.0-nightly-20260928023907
+## 0.0.0-nightly-20261027023041
 
 ### Patch Changes
 
 - Updated dependencies
-  - @backstage/config@0.0.0-nightly-20260928023907
-  - @backstage/core-components@0.0.0-nightly-20260928023907
-  - @backstage/core-plugin-api@0.0.0-nightly-20260928023907
-  - @backstage/frontend-plugin-api@0.0.0-nightly-20260928023907
-  - @backstage/catalog-model@0.0.0-nightly-20260928023907
+  - @backstage/frontend-plugin-api@0.0.0-nightly-20261027023041
+  - @backstage/core-plugin-api@0.0.0-nightly-20261027023041
+  - @backstage/catalog-model@1.10.2
+  - @backstage/config@1.3.10
+  - @backstage/core-components@0.0.0-nightly-20261027023041
   - @backstage/version-bridge@1.0.12
-  - @backstage/plugin-techdocs-common@0.1.1
+  - @backstage/plugin-techdocs-common@0.1.2
+
+## 1.4.0
+
+### Minor Changes
+
+- 4d4f987: Add engine abstraction layer for multi-engine TechDocs support. Introduces `--engine` flag, engine config map, generator registry with `backstage.io/techdocs-engine` annotation support, `engine` field in `techdocs_metadata.json`, `serve:raw` command, and live-reload adapter interface. MkDocs remains the default with no behavior change.
+
+  The built-in generator is now registered under `mkdocs`; the previous `techdocs` key is kept as an alias, so existing `generators.register('techdocs', ...)` calls continue to work. The CLI's `--engine` flag takes precedence over the `backstage.io/techdocs-engine` annotation for all commands, and `serve:mkdocs` and the `--mkdocs-parameter-*` flags now print deprecation warnings.
+
+### Patch Changes
+
+- f624dc6: Fixed Material UI styles for TechDocs addons in module-federated applications.
+- 450dd64: Isolated TechDocs addons in individual Suspense boundaries so that a lazy addon no longer hides the surrounding reader while it loads.
+- 7a4f545: Prevented TechDocs content from briefly appearing before page styles load.
+- Updated dependencies
+  - @backstage/frontend-plugin-api@0.18.2
+  - @backstage/config@1.3.10
+  - @backstage/core-components@0.18.15
+  - @backstage/plugin-techdocs-common@0.1.2
+  - @backstage/catalog-model@1.10.2
+  - @backstage/core-plugin-api@1.12.11
+
+## 1.3.16-next.2
+
+### Patch Changes
+
+- 450dd64: Isolated TechDocs addons in individual Suspense boundaries so that a lazy addon no longer hides the surrounding reader while it loads.
+- Updated dependencies
+  - @backstage/core-components@0.18.15-next.2
+  - @backstage/plugin-techdocs-common@0.1.2-next.0
+
+## 1.3.16-next.1
+
+### Patch Changes
+
+- f624dc6: Fixed Material UI styles for TechDocs addons in module-federated applications.
+- 7a4f545: Prevented TechDocs content from briefly appearing before page styles load.
+- Updated dependencies
+  - @backstage/core-components@0.18.15-next.1
 
 ## 1.3.16-next.0
 

package/dist/addons.esm.js

@@ -1,5 +1,5 @@
 import { jsx } from 'react/jsx-runtime';
-import { useCallback } from 'react';
+import { useCallback, Suspense } from 'react';
 import { useOutlet } from 'react-router-dom';
 import { attachComponentData, createReactExtension, useElementFilter } from '@backstage/core-plugin-api';
 
@@ -55,14 +55,15 @@ const useTechDocsAddons = () => {
   const renderComponentByName = useCallback(
     (name) => {
       const data = options.find((option) => option.name === name);
-      return data ? findAddonByData(data) : null;
+      const addon = data ? findAddonByData(data) : null;
+      return addon ? /* @__PURE__ */ jsx(Suspense, { fallback: null, children: addon }) : null;
     },
     [options, findAddonByData]
   );
   const renderComponentsByLocation = useCallback(
     (location) => {
       const data = options.filter((option) => option.location === location);
-      return data.length ? data.map(findAddonByData) : null;
+      return data.length ? data.map((option) => /* @__PURE__ */ jsx(Suspense, { fallback: null, children: findAddonByData(option) }, option.name)) : null;
     },
     [options, findAddonByData]
   );

package/dist/addons.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"addons.esm.js","sources":["../src/addons.tsx"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { PropsWithChildren, ComponentType, useCallback } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nimport {\n  attachComponentData,\n  createReactExtension,\n  ElementCollection,\n  Extension,\n  useElementFilter,\n} from '@backstage/core-plugin-api';\n\nimport { TechDocsAddonLocations, TechDocsAddonOptions } from './types';\n\n/**\n * Key for each addon.\n * @public\n */\nexport const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1';\n\n/**\n * Marks the `<TechDocsAddons>` registry component.\n * @public\n */\nexport const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';\n\n/**\n * TechDocs Addon registry.\n * @public\n */\nexport const TechDocsAddons: ComponentType<PropsWithChildren<{}>> = () => null;\n\nattachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);\n\nexport const getDataKeyByName = (name: string) => {\n  return `${TECHDOCS_ADDONS_KEY}.${name.toLowerCase()}`;\n};\n\n/**\n * Create a TechDocs addon overload signature without props.\n * @public\n */\nexport function createTechDocsAddonExtension(\n  options: TechDocsAddonOptions,\n): Extension<() => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon overload signature with props.\n * @public\n */\nexport function createTechDocsAddonExtension<TComponentProps>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon implementation.\n * @public\n */\nexport function createTechDocsAddonExtension<\n  TComponentProps extends PropsWithChildren<{}>,\n>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null> {\n  const { name, component: TechDocsAddon } = options;\n  return createReactExtension({\n    name,\n    component: {\n      sync: (props: TComponentProps) => <TechDocsAddon {...props} />,\n    },\n    data: {\n      [TECHDOCS_ADDONS_KEY]: options,\n      [getDataKeyByName(name)]: true,\n    },\n  });\n}\n\nconst getTechDocsAddonByName = (\n  collection: ElementCollection,\n  key: string,\n): JSX.Element | undefined => {\n  return collection.selectByComponentData({ key }).getElements()[0];\n};\n\nconst getAllTechDocsAddons = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\nconst getAllTechDocsAddonsData = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .findComponentData<TechDocsAddonOptions>({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\n/**\n * hook to use addons in components\n * @public\n */\nexport const useTechDocsAddons = () => {\n  const node = useOutlet();\n  const collection = useElementFilter(node, getAllTechDocsAddons);\n  const options = useElementFilter(node, getAllTechDocsAddonsData);\n\n  const findAddonByData = useCallback(\n    (data: TechDocsAddonOptions | undefined) => {\n      if (!collection || !data) return null;\n      const nameKey = getDataKeyByName(data.name);\n      return getTechDocsAddonByName(collection, nameKey) ?? null;\n    },\n    [collection],\n  );\n\n  const renderComponentByName = useCallback(\n    (name: string) => {\n      const data = options.find(option => option.name === name);\n      return data ? findAddonByData(data) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  const renderComponentsByLocation = useCallback(\n    (location: keyof typeof TechDocsAddonLocations) => {\n      const data = options.filter(option => option.location === location);\n      return data.length ? data.map(findAddonByData) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  return { renderComponentByName, renderComponentsByLocation };\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"addons.esm.js","sources":["../src/addons.tsx"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { PropsWithChildren, ComponentType, Suspense, useCallback } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nimport {\n  attachComponentData,\n  createReactExtension,\n  ElementCollection,\n  Extension,\n  useElementFilter,\n} from '@backstage/core-plugin-api';\n\nimport { TechDocsAddonLocations, TechDocsAddonOptions } from './types';\n\n/**\n * Key for each addon.\n * @public\n */\nexport const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1';\n\n/**\n * Marks the `<TechDocsAddons>` registry component.\n * @public\n */\nexport const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';\n\n/**\n * TechDocs Addon registry.\n * @public\n */\nexport const TechDocsAddons: ComponentType<PropsWithChildren<{}>> = () => null;\n\nattachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);\n\nexport const getDataKeyByName = (name: string) => {\n  return `${TECHDOCS_ADDONS_KEY}.${name.toLowerCase()}`;\n};\n\n/**\n * Create a TechDocs addon overload signature without props.\n * @public\n */\nexport function createTechDocsAddonExtension(\n  options: TechDocsAddonOptions,\n): Extension<() => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon overload signature with props.\n * @public\n */\nexport function createTechDocsAddonExtension<TComponentProps>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon implementation.\n * @public\n */\nexport function createTechDocsAddonExtension<\n  TComponentProps extends PropsWithChildren<{}>,\n>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null> {\n  const { name, component: TechDocsAddon } = options;\n  return createReactExtension({\n    name,\n    component: {\n      sync: (props: TComponentProps) => <TechDocsAddon {...props} />,\n    },\n    data: {\n      [TECHDOCS_ADDONS_KEY]: options,\n      [getDataKeyByName(name)]: true,\n    },\n  });\n}\n\nconst getTechDocsAddonByName = (\n  collection: ElementCollection,\n  key: string,\n): JSX.Element | undefined => {\n  return collection.selectByComponentData({ key }).getElements()[0];\n};\n\nconst getAllTechDocsAddons = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\nconst getAllTechDocsAddonsData = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .findComponentData<TechDocsAddonOptions>({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\n/**\n * Hook to use addons in components.\n *\n * Addons rendered through this hook are isolated in individual Suspense\n * boundaries with no fallback, so a suspended addon does not hide the reader\n * or sibling addons while it loads.\n *\n * @public\n */\nexport const useTechDocsAddons = () => {\n  const node = useOutlet();\n  const collection = useElementFilter(node, getAllTechDocsAddons);\n  const options = useElementFilter(node, getAllTechDocsAddonsData);\n\n  const findAddonByData = useCallback(\n    (data: TechDocsAddonOptions | undefined) => {\n      if (!collection || !data) return null;\n      const nameKey = getDataKeyByName(data.name);\n      return getTechDocsAddonByName(collection, nameKey) ?? null;\n    },\n    [collection],\n  );\n\n  const renderComponentByName = useCallback(\n    (name: string): JSX.Element | null => {\n      const data = options.find(option => option.name === name);\n      const addon = data ? findAddonByData(data) : null;\n      return addon ? <Suspense fallback={null}>{addon}</Suspense> : null;\n    },\n    [options, findAddonByData],\n  );\n\n  const renderComponentsByLocation = useCallback(\n    (\n      location: keyof typeof TechDocsAddonLocations,\n    ): (JSX.Element | null)[] | null => {\n      const data = options.filter(option => option.location === location);\n      return data.length\n        ? data.map(option => (\n            <Suspense key={option.name} fallback={null}>\n              {findAddonByData(option)}\n            </Suspense>\n          ))\n        : null;\n    },\n    [options, findAddonByData],\n  );\n\n  return { renderComponentByName, renderComponentsByLocation };\n};\n"],"names":[],"mappings":"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"}

package/dist/alpha.d.ts

@@ -1,7 +1,7 @@
 import * as _backstage_frontend_plugin_api from '@backstage/frontend-plugin-api';
 import { ComponentType } from 'react';
-import { T as TechDocsAddonOptions } from './types/types.d-Bva8_FYi.js';
-export { a as TechDocsAddonLocations } from './types/types.d-Bva8_FYi.js';
+import { T as TechDocsAddonOptions } from './types/types.d-DNS0ygON.js';
+export { a as TechDocsAddonLocations } from './types/types.d-DNS0ygON.js';
 import '@backstage/catalog-model';
 
 /**

package/dist/component.esm.js

@@ -1,8 +1,7 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
-import { useState, useCallback, useEffect } from 'react';
+import { useState, useCallback, useLayoutEffect, useEffect } from 'react';
 import { create } from 'jss';
-import StylesProvider from '@material-ui/styles/StylesProvider';
-import jssPreset from '@material-ui/styles/jssPreset';
+import { jssPreset, StylesProvider } from '@material-ui/styles';
 
 const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
 const useShadowDomStylesEvents = (element) => {
@@ -11,10 +10,12 @@ const useShadowDomStylesEvents = (element) => {
       return () => {
       };
     }
-    const styles = element.querySelectorAll(
-      'head > link[rel="stylesheet"]'
-    );
-    let count = styles?.length ?? 0;
+    const styles = Array.from(
+      element.querySelectorAll(
+        'head > link[rel="stylesheet"]'
+      )
+    ).filter((style) => !style.sheet);
+    let count = styles.length;
     const event = new CustomEvent(SHADOW_DOM_STYLE_LOAD_EVENT);
     if (!count) {
       element.dispatchEvent(event);
@@ -26,11 +27,11 @@ const useShadowDomStylesEvents = (element) => {
         element.dispatchEvent(event);
       }
     };
-    styles?.forEach((style) => {
+    styles.forEach((style) => {
       style.addEventListener("load", handleLoad);
     });
     return () => {
-      styles?.forEach((style) => {
+      styles.forEach((style) => {
         style.removeEventListener("load", handleLoad);
       });
     };
@@ -38,7 +39,7 @@ const useShadowDomStylesEvents = (element) => {
 };
 const useShadowDomStylesLoading = (element) => {
   const [loading, setLoading] = useState(false);
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (!element) return () => {
     };
     setLoading(true);

package/dist/component.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.esm.js","sources":["../src/component.tsx"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { PropsWithChildren, useState, useEffect, useCallback } from 'react';\n\nimport { create } from 'jss';\nimport StylesProvider from '@material-ui/styles/StylesProvider';\nimport jssPreset from '@material-ui/styles/jssPreset';\n\n/**\n * Name for the event dispatched when ShadowRoot styles are loaded.\n * @public\n */\nexport const SHADOW_DOM_STYLE_LOAD_EVENT = 'TECH_DOCS_SHADOW_DOM_STYLE_LOAD';\n\n/**\n * Dispatch style load event after all styles are loaded.\n * @param element - the ShadowRoot tree.\n */\nconst useShadowDomStylesEvents = (element: Element | null) => {\n  useEffect(() => {\n    if (!element) {\n      return () => {};\n    }\n\n    const styles = element.querySelectorAll<HTMLElement>(\n      'head > link[rel=\"stylesheet\"]',\n    );\n\n    let count = styles?.length ?? 0;\n    const event = new CustomEvent(SHADOW_DOM_STYLE_LOAD_EVENT);\n\n    if (!count) {\n      element.dispatchEvent(event);\n      return () => {};\n    }\n\n    const handleLoad = () => {\n      if (--count === 0) {\n        element.dispatchEvent(event);\n      }\n    };\n\n    styles?.forEach(style => {\n      style.addEventListener('load', handleLoad);\n    });\n\n    return () => {\n      styles?.forEach(style => {\n        style.removeEventListener('load', handleLoad);\n      });\n    };\n  }, [element]);\n};\n\n/**\n * Returns the style's loading state.\n *\n * @example\n * Here's an example that updates the sidebar position only after styles are calculated:\n * ```jsx\n * import {\n *   TechDocsShadowDom,\n *   useShadowDomStylesLoading,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = () => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *   const isStyleLoading = useShadowDomStylesLoading(dom);\n *\n *   const updateSidebarPosition = useCallback(() => {\n *     //...\n *   }, [dom]);\n *\n *   useEffect(() => {\n *     if (!isStyleLoading) {\n *       updateSidebarPosition();\n *     }\n *   }, [isStyleLoading, updateSidebarPosition]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param element - which is the ShadowRoot tree.\n * @returns a boolean value, true if styles are being loaded.\n * @public\n */\nexport const useShadowDomStylesLoading = (element: Element | null) => {\n  const [loading, setLoading] = useState(false);\n\n  useEffect(() => {\n    if (!element) return () => {};\n\n    setLoading(true);\n\n    const style = (element as HTMLElement).style;\n\n    style.setProperty('opacity', '0');\n\n    const handleLoad = () => {\n      setLoading(false);\n      style.setProperty('opacity', '1');\n    };\n\n    element.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n\n    return () => {\n      element.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n    };\n  }, [element]);\n\n  return loading;\n};\n\n/**\n * Props for {@link TechDocsShadowDom}.\n *\n * @remarks\n * If you want to use portals to render Material UI components in the Shadow DOM,\n * you must render these portals as children because this component wraps its children in a Material UI StylesProvider\n * to ensure that Material UI styles are applied.\n *\n * @public\n */\nexport type TechDocsShadowDomProps = PropsWithChildren<{\n  /**\n   * Element tree that is appended to ShadowRoot.\n   */\n  element: Element;\n  /**\n   * Callback called when the element tree is appended in ShadowRoot.\n   */\n  onAppend?: (shadowRoot: ShadowRoot) => void;\n}>;\n\n/**\n * Renders a tree of elements in a Shadow DOM.\n *\n * @remarks\n * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,\n * so if you want to know when Shadow DOM styles are computed, you can listen for the \"TECH_DOCS_SHADOW_DOM_STYLE_LOAD\" event dispatched by the element tree.\n *\n * @example\n * Here is an example using this component and also listening for styles loaded event:\n *```jsx\n * import {\n *   TechDocsShadowDom,\n *   SHADOW_DOM_STYLE_LOAD_EVENT,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *\n *   useEffect(() => {\n *     const updateSidebarPosition = () => {\n *       // ...\n *     };\n *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     return () => {\n *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     };\n *   }, [dom]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param props - see {@link TechDocsShadowDomProps}.\n * @public\n */\nexport const TechDocsShadowDom = (props: TechDocsShadowDomProps) => {\n  const { element, onAppend, children } = props;\n\n  const [jss, setJss] = useState(\n    create({\n      ...jssPreset(),\n      insertionPoint: undefined,\n    }),\n  );\n\n  useShadowDomStylesEvents(element);\n\n  const ref = useCallback(\n    (shadowHost: HTMLDivElement) => {\n      if (!element || !shadowHost) return;\n\n      setJss(\n        create({\n          ...jssPreset(),\n          insertionPoint: element.querySelector('head') || undefined,\n        }),\n      );\n\n      let shadowRoot = shadowHost.shadowRoot;\n\n      if (!shadowRoot) {\n        shadowRoot = shadowHost.attachShadow({ mode: 'open' });\n      }\n\n      shadowRoot.replaceChildren(element);\n\n      if (typeof onAppend === 'function') {\n        onAppend(shadowRoot);\n      }\n    },\n    [element, onAppend],\n  );\n\n  return (\n    <>\n      {/* The sheetsManager={new Map()} is needed in order to deduplicate the injection of CSS in the page. */}\n      <StylesProvider jss={jss} sheetsManager={new Map()}>\n        <div ref={ref} data-testid=\"techdocs-native-shadowroot\" />\n        {children}\n      </StylesProvider>\n    </>\n  );\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"component.esm.js","sources":["../src/component.tsx"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  PropsWithChildren,\n  useState,\n  useEffect,\n  useLayoutEffect,\n  useCallback,\n} from 'react';\n\nimport { create } from 'jss';\n// The package-root import ensures federated apps share the same styling context.\n// eslint-disable-next-line @backstage/no-top-level-material-ui-4-imports\nimport { StylesProvider, jssPreset } from '@material-ui/styles';\n\n/**\n * Name for the event dispatched when ShadowRoot styles are loaded.\n * @public\n */\nexport const SHADOW_DOM_STYLE_LOAD_EVENT = 'TECH_DOCS_SHADOW_DOM_STYLE_LOAD';\n\n/**\n * Dispatch style load event after all styles are loaded.\n * @param element - the ShadowRoot tree.\n */\nconst useShadowDomStylesEvents = (element: Element | null) => {\n  // Keep this passive so consumers can subscribe from a layout effect before\n  // already-loaded styles dispatch the event synchronously.\n  useEffect(() => {\n    if (!element) {\n      return () => {};\n    }\n\n    const styles = Array.from(\n      element.querySelectorAll<HTMLLinkElement>(\n        'head > link[rel=\"stylesheet\"]',\n      ),\n    ).filter(style => !style.sheet);\n\n    let count = styles.length;\n    const event = new CustomEvent(SHADOW_DOM_STYLE_LOAD_EVENT);\n\n    if (!count) {\n      element.dispatchEvent(event);\n      return () => {};\n    }\n\n    const handleLoad = () => {\n      if (--count === 0) {\n        element.dispatchEvent(event);\n      }\n    };\n\n    styles.forEach(style => {\n      style.addEventListener('load', handleLoad);\n    });\n\n    return () => {\n      styles.forEach(style => {\n        style.removeEventListener('load', handleLoad);\n      });\n    };\n  }, [element]);\n};\n\n/**\n * Returns the style's loading state.\n *\n * Hides the element before paint and reveals it after the\n * {@link SHADOW_DOM_STYLE_LOAD_EVENT} event is dispatched.\n *\n * @example\n * Here's an example that updates the sidebar position only after styles are calculated:\n * ```jsx\n * import {\n *   TechDocsShadowDom,\n *   useShadowDomStylesLoading,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = () => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *   const isStyleLoading = useShadowDomStylesLoading(dom);\n *\n *   const updateSidebarPosition = useCallback(() => {\n *     //...\n *   }, [dom]);\n *\n *   useEffect(() => {\n *     if (!isStyleLoading) {\n *       updateSidebarPosition();\n *     }\n *   }, [isStyleLoading, updateSidebarPosition]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param element - which is the ShadowRoot tree.\n * @returns a boolean value, true if styles are being loaded.\n * @public\n */\nexport const useShadowDomStylesLoading = (element: Element | null) => {\n  const [loading, setLoading] = useState(false);\n\n  useLayoutEffect(() => {\n    if (!element) return () => {};\n\n    setLoading(true);\n\n    const style = (element as HTMLElement).style;\n\n    style.setProperty('opacity', '0');\n\n    const handleLoad = () => {\n      setLoading(false);\n      style.setProperty('opacity', '1');\n    };\n\n    element.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n\n    return () => {\n      element.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n    };\n  }, [element]);\n\n  return loading;\n};\n\n/**\n * Props for {@link TechDocsShadowDom}.\n *\n * @remarks\n * If you want to use portals to render Material UI components in the Shadow DOM,\n * you must render these portals as children because this component wraps its children in a Material UI StylesProvider\n * to ensure that Material UI styles are applied.\n *\n * @public\n */\nexport type TechDocsShadowDomProps = PropsWithChildren<{\n  /**\n   * Element tree that is appended to ShadowRoot.\n   */\n  element: Element;\n  /**\n   * Callback called when the element tree is appended in ShadowRoot.\n   */\n  onAppend?: (shadowRoot: ShadowRoot) => void;\n}>;\n\n/**\n * Renders a tree of elements in a Shadow DOM.\n *\n * @remarks\n * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,\n * so if you want to know when Shadow DOM styles are computed, you can listen for the \"TECH_DOCS_SHADOW_DOM_STYLE_LOAD\" event dispatched by the element tree.\n *\n * @example\n * Here is an example using this component and also listening for styles loaded event:\n *```jsx\n * import {\n *   TechDocsShadowDom,\n *   SHADOW_DOM_STYLE_LOAD_EVENT,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *\n *   useEffect(() => {\n *     const updateSidebarPosition = () => {\n *       // ...\n *     };\n *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     return () => {\n *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     };\n *   }, [dom]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param props - see {@link TechDocsShadowDomProps}.\n * @public\n */\nexport const TechDocsShadowDom = (props: TechDocsShadowDomProps) => {\n  const { element, onAppend, children } = props;\n\n  const [jss, setJss] = useState(\n    create({\n      ...jssPreset(),\n      insertionPoint: undefined,\n    }),\n  );\n\n  useShadowDomStylesEvents(element);\n\n  const ref = useCallback(\n    (shadowHost: HTMLDivElement) => {\n      if (!element || !shadowHost) return;\n\n      setJss(\n        create({\n          ...jssPreset(),\n          insertionPoint: element.querySelector('head') || undefined,\n        }),\n      );\n\n      let shadowRoot = shadowHost.shadowRoot;\n\n      if (!shadowRoot) {\n        shadowRoot = shadowHost.attachShadow({ mode: 'open' });\n      }\n\n      shadowRoot.replaceChildren(element);\n\n      if (typeof onAppend === 'function') {\n        onAppend(shadowRoot);\n      }\n    },\n    [element, onAppend],\n  );\n\n  return (\n    <>\n      {/* The sheetsManager={new Map()} is needed in order to deduplicate the injection of CSS in the page. */}\n      <StylesProvider jss={jss} sheetsManager={new Map()}>\n        <div ref={ref} data-testid=\"techdocs-native-shadowroot\" />\n        {children}\n      </StylesProvider>\n    </>\n  );\n};\n"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ComponentType, PropsWithChildren, Dispatch, SetStateAction, ReactNode } from 'react';
 import { Extension, RouteFunc } from '@backstage/core-plugin-api';
-import { T as TechDocsAddonOptions, a as TechDocsAddonLocations, b as TechDocsMetadata, c as TechDocsEntityMetadata } from './types/types.d-Bva8_FYi.js';
+import { T as TechDocsAddonOptions, a as TechDocsAddonLocations, b as TechDocsMetadata, c as TechDocsEntityMetadata } from './types/types.d-DNS0ygON.js';
 import * as _backstage_frontend_plugin_api from '@backstage/frontend-plugin-api';
 import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -34,7 +34,12 @@ declare function createTechDocsAddonExtension(options: TechDocsAddonOptions): Ex
  */
 declare function createTechDocsAddonExtension<TComponentProps>(options: TechDocsAddonOptions<TComponentProps>): Extension<(props: TComponentProps) => JSX.Element | null>;
 /**
- * hook to use addons in components
+ * Hook to use addons in components.
+ *
+ * Addons rendered through this hook are isolated in individual Suspense
+ * boundaries with no fallback, so a suspended addon does not hide the reader
+ * or sibling addons while it loads.
+ *
  * @public
  */
 declare const useTechDocsAddons: () => {
@@ -139,6 +144,9 @@ declare const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
 /**
  * Returns the style's loading state.
  *
+ * Hides the element before paint and reveals it after the
+ * {@link SHADOW_DOM_STYLE_LOAD_EVENT} event is dispatched.
+ *
  * @example
  * Here's an example that updates the sidebar position only after styles are calculated:
  * ```jsx

package/dist/types/{types.d-Bva8_FYi.d.ts → types.d-DNS0ygON.d.ts}

@@ -9,6 +9,7 @@ import { Entity } from '@backstage/catalog-model';
 type TechDocsMetadata = {
     site_name: string;
     site_description: string;
+    engine?: string;
 };
 /**
  * Metadata for TechDocs Entity

package/dist/types.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.esm.js","sources":["../src/types.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ComponentType } from 'react';\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Metadata for TechDocs page\n *\n * @public\n */\nexport type TechDocsMetadata = {\n  site_name: string;\n  site_description: string;\n};\n\n/**\n * Metadata for TechDocs Entity\n *\n * @public\n */\nexport type TechDocsEntityMetadata = Entity & {\n  locationMetadata?: { type: string; target: string };\n};\n\n/**\n * Locations for which TechDocs addons may be declared and rendered.\n * @public\n */\nexport const TechDocsAddonLocations = Object.freeze({\n  /**\n   * These addons fill up the header from the right, on the same line as the\n   * title.\n   */\n  Header: 'Header',\n\n  /**\n   * These addons appear below the header and above all content; tooling addons\n   * can be inserted for convenience.\n   */\n  Subheader: 'Subheader',\n\n  /**\n   * These addons are items added to the settings menu list and are designed to make\n   * the reader experience customizable, for example accessibility options\n   */\n  Settings: 'Settings',\n\n  /**\n   * These addons appear left of the content and above the navigation.\n   */\n  PrimarySidebar: 'PrimarySidebar',\n\n  /**\n   * These addons appear right of the content and above the table of contents.\n   */\n  SecondarySidebar: 'SecondarySidebar',\n\n  /**\n   * A virtual location which allows mutation of all content within the shadow\n   * root by transforming DOM nodes. These addons should return null on render.\n   */\n  Content: 'Content',\n\n  /**\n   * todo(backstage/community): This is a proposed virtual location which would\n   * help implement a common addon pattern in which many instances of a given\n   * element in markdown would be dynamically replaced at render-time based on\n   * attributes provided on that element, for example:\n   *\n   * ```md\n   * ## For Fun\n   * <TechDocsAddon>CatGif</TechDocsAddon>\n   *\n   * ## Component Metadata\n   * <TechDocsAddon entityRef=\"default:component/some-component-name\">CatalogEntityCard</TechDocsAddon>\n   *\n   * ## System Metadata\n   * <TechDocsAddon entityRef=\"default:system/some-system-name\">CatalogEntityCard</TechDocsAddon>\n   * ```\n   *\n   * Could correspond to a TechDocs addon named `CatalogEntityCard` with\n   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be\n   * the react component that would be rendered in place of all instances of\n   * the markdown illustrated above.\n   *\n   * The `@backstage/plugin-techdocs-react` package would need to be updated to, in\n   * cases where such addons had been registered, find all instances of the\n   * the `<TechDocsAddon>` tag whose `textContent` corresponded with the name of the\n   * addon, then replace them with component instances of the addon component,\n   * passing any attributes from the tag as props to the component.\n   */\n  // Component: 'Component',\n} as const);\n\n/**\n * Options for creating a TechDocs addon.\n * @public\n */\nexport type TechDocsAddonOptions<TAddonProps = {}> = {\n  name: string;\n  location: keyof typeof TechDocsAddonLocations;\n  component: ComponentType<TAddonProps>;\n};\n"],"names":[],"mappings":"AA0CO,MAAM,sBAAA,GAAyB,OAAO,MAAA,CAAO;AAAA;AAAA;AAAA;AAAA;AAAA,EAKlD,MAAA,EAAQ,QAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,SAAA,EAAW,WAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMX,QAAA,EAAU,UAAA;AAAA;AAAA;AAAA;AAAA,EAKV,cAAA,EAAgB,gBAAA;AAAA;AAAA;AAAA;AAAA,EAKhB,gBAAA,EAAkB,kBAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMlB,OAAA,EAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+BX,CAAU;;"}
+{"version":3,"file":"types.esm.js","sources":["../src/types.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ComponentType } from 'react';\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Metadata for TechDocs page\n *\n * @public\n */\nexport type TechDocsMetadata = {\n  site_name: string;\n  site_description: string;\n  engine?: string;\n};\n\n/**\n * Metadata for TechDocs Entity\n *\n * @public\n */\nexport type TechDocsEntityMetadata = Entity & {\n  locationMetadata?: { type: string; target: string };\n};\n\n/**\n * Locations for which TechDocs addons may be declared and rendered.\n * @public\n */\nexport const TechDocsAddonLocations = Object.freeze({\n  /**\n   * These addons fill up the header from the right, on the same line as the\n   * title.\n   */\n  Header: 'Header',\n\n  /**\n   * These addons appear below the header and above all content; tooling addons\n   * can be inserted for convenience.\n   */\n  Subheader: 'Subheader',\n\n  /**\n   * These addons are items added to the settings menu list and are designed to make\n   * the reader experience customizable, for example accessibility options\n   */\n  Settings: 'Settings',\n\n  /**\n   * These addons appear left of the content and above the navigation.\n   */\n  PrimarySidebar: 'PrimarySidebar',\n\n  /**\n   * These addons appear right of the content and above the table of contents.\n   */\n  SecondarySidebar: 'SecondarySidebar',\n\n  /**\n   * A virtual location which allows mutation of all content within the shadow\n   * root by transforming DOM nodes. These addons should return null on render.\n   */\n  Content: 'Content',\n\n  /**\n   * todo(backstage/community): This is a proposed virtual location which would\n   * help implement a common addon pattern in which many instances of a given\n   * element in markdown would be dynamically replaced at render-time based on\n   * attributes provided on that element, for example:\n   *\n   * ```md\n   * ## For Fun\n   * <TechDocsAddon>CatGif</TechDocsAddon>\n   *\n   * ## Component Metadata\n   * <TechDocsAddon entityRef=\"default:component/some-component-name\">CatalogEntityCard</TechDocsAddon>\n   *\n   * ## System Metadata\n   * <TechDocsAddon entityRef=\"default:system/some-system-name\">CatalogEntityCard</TechDocsAddon>\n   * ```\n   *\n   * Could correspond to a TechDocs addon named `CatalogEntityCard` with\n   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be\n   * the react component that would be rendered in place of all instances of\n   * the markdown illustrated above.\n   *\n   * The `@backstage/plugin-techdocs-react` package would need to be updated to, in\n   * cases where such addons had been registered, find all instances of the\n   * the `<TechDocsAddon>` tag whose `textContent` corresponded with the name of the\n   * addon, then replace them with component instances of the addon component,\n   * passing any attributes from the tag as props to the component.\n   */\n  // Component: 'Component',\n} as const);\n\n/**\n * Options for creating a TechDocs addon.\n * @public\n */\nexport type TechDocsAddonOptions<TAddonProps = {}> = {\n  name: string;\n  location: keyof typeof TechDocsAddonLocations;\n  component: ComponentType<TAddonProps>;\n};\n"],"names":[],"mappings":"AA2CO,MAAM,sBAAA,GAAyB,OAAO,MAAA,CAAO;AAAA;AAAA;AAAA;AAAA;AAAA,EAKlD,MAAA,EAAQ,QAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,SAAA,EAAW,WAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMX,QAAA,EAAU,UAAA;AAAA;AAAA;AAAA;AAAA,EAKV,cAAA,EAAgB,gBAAA;AAAA;AAAA;AAAA;AAAA,EAKhB,gBAAA,EAAkB,kBAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMlB,OAAA,EAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+BX,CAAU;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-react",
-  "version": "0.0.0-nightly-20260928023907",
+  "version": "0.0.0-nightly-20261027023041",
   "description": "Shared frontend utilities for TechDocs and Addons",
   "backstage": {
     "role": "web-library",
@@ -66,12 +66,12 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/catalog-model": "0.0.0-nightly-20260928023907",
-    "@backstage/config": "0.0.0-nightly-20260928023907",
-    "@backstage/core-components": "0.0.0-nightly-20260928023907",
-    "@backstage/core-plugin-api": "0.0.0-nightly-20260928023907",
-    "@backstage/frontend-plugin-api": "0.0.0-nightly-20260928023907",
-    "@backstage/plugin-techdocs-common": "0.1.1",
+    "@backstage/catalog-model": "1.10.2",
+    "@backstage/config": "1.3.10",
+    "@backstage/core-components": "0.0.0-nightly-20261027023041",
+    "@backstage/core-plugin-api": "0.0.0-nightly-20261027023041",
+    "@backstage/frontend-plugin-api": "0.0.0-nightly-20261027023041",
+    "@backstage/plugin-techdocs-common": "0.1.2",
     "@backstage/version-bridge": "1.0.12",
     "@material-ui/core": "^4.12.2",
     "@material-ui/styles": "^4.11.0",
@@ -80,8 +80,8 @@
     "react-use": "^17.2.4"
   },
   "devDependencies": {
-    "@backstage/cli": "0.0.0-nightly-20260928023907",
-    "@backstage/test-utils": "0.0.0-nightly-20260928023907",
+    "@backstage/cli": "0.0.0-nightly-20261027023041",
+    "@backstage/test-utils": "0.0.0-nightly-20261027023041",
     "@backstage/theme": "0.7.3",
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.0.0",