@show-docs/docusaurus-theme-iframe 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @show-docs/docusaurus-theme-iframe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把文档页整页替换成 iframe 的 Docusaurus 主题插件。frontmatter 写 `iframe:`、`scalar:`、`redoc:`
+或 `oas3:` 时，命中的页面保留站点 navbar，正文区换成一个 iframe。
+
+`iframe:` 由本包直接处理，用来嵌外部页面；`scalar:` / `redoc:` / `oas3:` 分别由 theme-scalar、
+theme-redoc、theme-stoplight 在框内渲染，本包负责外层套壳与跨 iframe 的地址、亮暗同步。
+
+## 安装
+
+```bash
+pnpm add @show-docs/docusaurus-theme-iframe
+```
+
+## 使用
+
+### 注册插件
+
+```js
+// docusaurus.config.mjs
+export default {
+  plugins: ['@show-docs/docusaurus-theme-iframe']
+};
+```
+
+使用 API 三把键时，同时注册对应的渲染包：
+
+```js
+[
+  '@show-docs/docusaurus-theme-iframe',
+  '@show-docs/docusaurus-theme-stoplight',
+  '@show-docs/docusaurus-theme-redoc',
+  '@show-docs/docusaurus-theme-scalar'
+];
+```
+
+### 写 frontmatter
+
+```md
+---
+title: 外部文档
+iframe: https://example.com/handbook/
+---
+```
+
+| 键       | 渲染方                                  | 值的含义         |
+| -------- | --------------------------------------- | ---------------- |
+| `iframe` | 本包                                    | 要嵌入的页面地址 |
+| `scalar` | `@show-docs/docusaurus-theme-scalar`    | OpenAPI 文档地址 |
+| `redoc`  | `@show-docs/docusaurus-theme-redoc`     | OpenAPI 文档地址 |
+| `oas3`   | `@show-docs/docusaurus-theme-stoplight` | OpenAPI 文档地址 |
+
+`iframe:` 的值原样使用；以 `/` 开头时按当前站点 origin 补成绝对地址。地址栏带
+`?path=<相对路径>` 时，会在该地址之下再解析一层，用来切换外部站点的子页面。
+
+## 配置
+
+只有一个可选插件选项，用于覆盖本包判键的顺序和启用范围：
+
+```js
+[
+  [
+    '@show-docs/docusaurus-theme-iframe',
+    {
+      themeConfig: {
+        apiFrame: {
+          order: [
+            '@show-docs/docusaurus-theme-redoc',
+            '@show-docs/docusaurus-theme-stoplight',
+            '@show-docs/docusaurus-theme-iframe'
+          ]
+        }
+      }
+    }
+  ]
+];
+```
+
+| 选项                         | 类型       | 默认值                                 | 说明                                                         |
+| ---------------------------- | ---------- | -------------------------------------- | ------------------------------------------------------------ |
+| `themeConfig.apiFrame.order` | `string[]` | `scalar` → `redoc` → `oas3` → `iframe` | 判定顺序与启用范围；排在前面的层优先，未列出的层不参与判定。 |
+
+覆盖不会绕过「已安装」这一条：清单里列了但 `plugins` 里没装的层仍然不参与判定。同一页写了多
+把键时，按顺序取第一个命中的已安装层。开发模式下，写了键却没有层接收会在控制台给出告警。
+
+## 工作方式
+
+- 命中时用 iframe 替换整个 `DocItem`：不渲染面包屑、正文、右侧目录和翻页，站点 navbar 保留。
+- 页面占满 navbar 以下的一屏，并隐藏站点页脚；框的版式由四条层共用一份样式。
+- 三个 API 包的框内页面（`/scalar-view`、`/redoc-view`、`/stoplight-view`）与本包通过
+  `postMessage` 同步地址栏 `#` 段和亮暗模式；`iframe:` 嵌外部站点时没有这条通道。
+- 与 `theme-markmap` 同页使用且两把键都命中时，导图渲染在 iframe 上方。
+
+## 已知限制
+
+- 外部站点设置了 `X-Frame-Options` 或 CSP `frame-ancestors` 时，iframe 区域会空白；这是浏览器
+  拒绝嵌入，不是本插件报错。
+- 外部 iframe 的内容与站点主题、亮暗模式、路由互不影响；跨源页面也没有可配合的代码。
+- 命中页不渲染官方 `DocItem/Metadata`，浏览器标签页标题与 `<meta name="description">` 退回
+  站点默认值，不读该页的 `title:` / `description:`。
+- 承载 iframe 的容器会通过 `.container:has(iframe)` 去掉内边距；正文里手写的 iframe 同样命中
+  这条样式。
+- 对应插件未安装时，frontmatter 里的键不生效，页面按普通文档渲染。
+
+## 相关文档
+
+- [维护者文档](./docs/internals.md)：包内组成、编译方式、新增一条 API 层的步骤。
+- [跨 iframe 协议](./docs/iframe-protocol.md)：地址与亮暗同步的消息形状、两侧的监听。
+- [iframe 示例](../../docs/iframe-demo.md)。

package/components/api-frame.css

@@ -0,0 +1,38 @@
+/* 「整页交给一个框」这一族四条层**共用**的那一格版式：类名由 `components/api-frame.tsx`
+   同时挂在 `<iframe>` 上（`api-frame` 是这一族共用的那一个，注册表那条 `frameClass` 是各层
+   专属的第二个类名，只属于一层的规则挂在那一个上）。
+
+   定高取 `100vh - var(--ifm-navbar-height)`：滚动条长在**框内那份文档**上，那份文档没有
+   navbar，整屏都是它的，外层这一格给多高它就占多高，两层滚动容器各滚各的文档，互不打扰。
+   `display: block` 与 `border: 0` 收的是浏览器对 `<iframe>` 的两个默认（inline、带边框）。
+
+   正文容器那一格由下面那条裸 `iframe` 规则负责（去内边距、放开最大宽度）—— 各层不再重复写
+   `.container:has(.X-frame)`。`max-width: 100%` 与 `unset` 在这里等价：那一格是
+   `.container` 自己，父链上没有别的宽度约束，两个值都落到「铺满」，所以只留一条。
+
+   这条按「这一格里有 iframe」匹配 —— 正文里手写的 iframe 也会让承载它的容器去掉内边距，
+   这是它本来就声明的全站边界，不是疏漏。
+
+   页脚那一格同理是**这一族共有的**：框已经占满 navbar 以下那一屏，页脚留在下面只会被推出
+   可视区，于是这一页多出一条只能滚到页脚的空白（配了 `themeConfig.footer` 才看得见，实测
+   238px）。以前这条只写在 `theme-stoplight` 自己那份里、认的是 `stoplight-frame` 那个类名，
+   所以 redoc / scalar / 外部 iframe 三条一律漏掉 —— 收进这一份、键在四把层都挂的
+   `api-frame` 上。Docusaurus 的 classic 布局里 `.footer` 是 `.main-wrapper` 的**紧邻后兄弟**，
+   选择器就照这个形状写；认 `api-frame` 而不认裸 `iframe`，正文里手写的 iframe 不该顺带把
+   整站页脚收掉。 */
+
+.api-frame {
+  display: block;
+  border: 0;
+  width: 100%;
+  height: calc(100vh - var(--ifm-navbar-height));
+}
+
+.container:has(iframe) {
+  padding: 0 !important;
+  max-width: 100% !important;
+}
+
+.main-wrapper:has(.api-frame) + .footer {
+  display: none;
+}

package/components/api-frame.tsx

@@ -0,0 +1,116 @@
+/**
+外层文档页里那一个通用框：三条 API 层与 `iframe:` 那一层共用这一份渲染，形状由注册表里那一条
+决定（`lib/api-frame-registry.ts`）。
+
+- `internal`：`src` 由 `frameViewSrc()` 拼（spec 编码进去、`hash` 不进去，服务端与客户端算出
+  同一个字符串），深链那一段与亮暗靠 `useOuterFrameSync` 送（那条循环与踩过的坑在
+  `lib/frame-sync.ts` 与 `docs/iframe-protocol.md`）。
+- `external`：框里是**外部站点**，跨源，没有那条通道；地址那三步在 `lib/frame-messages.ts` 的
+  `externalFrameURL()`，与框内取 spec 那条同形状，所以也在覆盖率红线里。
+
+`<iframe>` 恒挂两个类名：共用的 `.api-frame`（尺寸与容器让位，四条层同一条式子）与注册表那条
+`frameClass`（认「哪一层赢了」，只属于一层的规则挂它）。这一格只剩一个 `<iframe>` 与一个 hook，
+没有渲染器依赖，所以 `DocItem` 静态 import 它，不走 lazy/Suspense。
+*/
+
+import './api-frame.css';
+
+import { useMemo, useRef } from 'react';
+import type { ReactNode } from 'react';
+
+import { useLocation } from '@docusaurus/router';
+import { useColorMode } from '@docusaurus/theme-common';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+import { apiFrameMessages } from '../lib/api-frame-messages.ts';
+import type { ApiFrameEntry } from '../lib/api-frame-registry.ts';
+import {
+  externalFrameURL,
+  frameViewSrc,
+  type FrameColorMode,
+} from '../lib/frame-messages.ts';
+import { useOuterFrameSync } from '../lib/frame-sync.ts';
+
+type Props = {
+  entry: ApiFrameEntry;
+  value: string;
+  /** 页面自己的 `frontMatter.title`；有它就用它当框的无障碍标题，注册表那条 `title` 只是兜底。 */
+  frontMatterTitle?: unknown;
+};
+
+export function ApiFrame({ entry, value, frontMatterTitle }: Props): ReactNode {
+  const frameClass = `api-frame ${entry.frameClass}`;
+  const title =
+    typeof frontMatterTitle === 'string' && frontMatterTitle !== ''
+      ? frontMatterTitle
+      : entry.title;
+
+  return entry.kind === 'external' ? (
+    <ExternalFrame frameClass={frameClass} src={value} title={title} />
+  ) : (
+    <InternalFrame
+      entry={entry}
+      frameClass={frameClass}
+      specUrl={value}
+      title={title}
+    />
+  );
+}
+
+function InternalFrame({
+  entry,
+  frameClass,
+  specUrl,
+  title,
+}: {
+  entry: Extract<ApiFrameEntry, { kind: 'internal' }>;
+  frameClass: string;
+  specUrl: string;
+  title: string;
+}): ReactNode {
+  const { siteConfig } = useDocusaurusContext();
+  const { colorMode } = useColorMode();
+  const frameRef = useRef<HTMLIFrameElement>(null);
+
+  const src = frameViewSrc({
+    baseUrl: siteConfig.baseUrl,
+    route: entry.route,
+    specParam: entry.specParam,
+    specUrl,
+  });
+
+  useOuterFrameSync({
+    colorMode: colorMode as FrameColorMode,
+    frameRef,
+    messages: apiFrameMessages(entry.namespace),
+  });
+
+  return (
+    <iframe ref={frameRef} className={frameClass} src={src} title={title} />
+  );
+}
+
+function ExternalFrame({
+  frameClass,
+  src,
+  title,
+}: {
+  frameClass: string;
+  src: string;
+  title: string;
+}): ReactNode {
+  const { search } = useLocation();
+  const isBrowser = useIsBrowser();
+
+  // 服务端渲染阶段拿不到 `window`，那时 url 就是 frontmatter 里那个原值。
+  const url = useMemo(
+    () =>
+      isBrowser
+        ? externalFrameURL({ src, search, origin: window.location.origin })
+        : src,
+    [isBrowser, search, src],
+  );
+
+  return <iframe className={frameClass} src={url} title={title} />;
+}

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import type { Plugin } from '@docusaurus/types';
+export default function theme(): Plugin;

package/dist/index.mjs

@@ -0,0 +1,18 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 包出口是 `dist/`，所以这里的路径都相对**产物**目录算，不是相对 `src/`。
+const thisDir = dirname(fileURLToPath(import.meta.url));
+export default function theme() {
+    return {
+        name: '@show-docs/docusaurus-theme-iframe',
+        // 主题层与 `components/` 是**源码**，站在包根上，不经 `tsc`：用本包的 Docusaurus
+        // 项目会用自己的 babel 编译它们。本包要编译的只有这一份入口。
+        getThemePath() {
+            return resolve(thisDir, '../theme');
+        },
+        // 层里放的是 `.tsx`，这条给 `docusaurus swizzle` 用
+        getTypeScriptThemePath() {
+            return resolve(thisDir, '../theme');
+        },
+    };
+}

package/lib/api-frame-entries.ts

@@ -0,0 +1,195 @@
+/**
+本次渲染该按什么顺序判这几把键 —— 注册表给数据，站点给裁决权，**只有一条规则**：
+
+- 参与判定的层 = **装了的层**（`plugins` 里有其包名、或其包目录内入口路径的那一项）；
+- 顺序默认 = 注册表的清单顺序，站点可在本层插件选项
+  `['@show-docs/docusaurus-theme-iframe', { themeConfig: { apiFrame: { order: [...] } } }]`
+  里用命名空间数组覆盖顺序与子集。**覆盖不放宽装机过滤**：列了没装的层照样不判，否则
+  「指向不存在路由的框」这个失败模式会在覆盖下被重新引入。
+
+为什么读的是**原始 `plugins`** 而不是 `themeConfig`、那四种配置写法各怎么认，见
+`docs/iframe-protocol.md` 的「注册表与分发」一节。这一格吃的是 Docusaurus 的**实现细节**
+（浏览器配置序列化保留原始形状）而非公开承诺，`demo/scripts/verify-chain.mts` 第 3 节钉着它。
+
+落空的键（写了、层没装或被覆盖排除）进 `warnings`：装机过滤把旧的「照样命中、渲染一个坏框」
+换成「页面看着正常但键没生效」，所以手误不能静默 —— `DocItem` 在开发模式把那份清单交给
+`warnFrameDistribution()` 打到控制台，构建产物不打。
+
+这里只回答顺序与启用；route、类名、参数名那些数据在 `api-frame-registry.ts`。
+判定与打日志都不引 React，单测与 `DocItem` 引这同一份。
+*/
+
+import {
+  apiFrameByNamespace,
+  apiFrameEntriesOrdered,
+  type ApiFrameEntry,
+} from './api-frame-registry.ts';
+
+/** 本层的包名 = `plugins` 里那一项的名字 = 注册表里 external 条目的命名空间。 */
+const IFRAME_NAMESPACE = '@show-docs/docusaurus-theme-iframe';
+
+/** 覆盖清单的载体：插件选项那一格（`{ themeConfig: { apiFrame: { order } } }`）。 */
+type ApiFramePluginOptions = {
+  themeConfig?: { apiFrame?: { order?: string[] } };
+};
+
+/**
+从 `siteConfig.plugins` 的一项里取「名字 + 选项」。浏览器侧拿到的是**原始配置形状**，四种写法：
+- 字符串（裸包名或路径 —— 名字与层的对应关系见 `slotIsNamespace`）；
+- `[包名, 选项]`；
+- `[路径, 选项]`；
+- `{name}` 对象（归一化形状，兼容 `siteVersion` 那类元数据）。
+*/
+function readPluginSlot(plugin: unknown): {
+  name: string | undefined;
+  options: ApiFramePluginOptions | undefined;
+} {
+  if (typeof plugin === 'string') {
+    return { name: plugin, options: undefined };
+  }
+  if (Array.isArray(plugin)) {
+    return {
+      name: typeof plugin[0] === 'string' ? plugin[0] : undefined,
+      options: plugin[1] as ApiFramePluginOptions | undefined,
+    };
+  }
+  return {
+    name:
+      typeof plugin === 'object' && plugin !== null
+        ? (plugin as { name?: string }).name
+        : undefined,
+    options: undefined,
+  };
+}
+
+/**
+一个槽位的名格是不是这条层：裸包名相等，或**该包目录内任何入口**的绝对路径
+（`docusaurus-theme-x` 与去前缀的 `theme-x` 两种目录段都认 —— 按包目录认，不钉具体
+入口文件名；钉文件名会把「产物改名」变成静默失效）。装机判定与覆盖槽位识别共用这一条，
+两边不存在「一层认路径、另一层只认包名」的不对称。
+*/
+function slotIsNamespace(name: string, namespace: string): boolean {
+  if (name === namespace) {
+    return true;
+  }
+  const pathForm = name.replaceAll('\\', '/');
+  // 去掉 `@scope/` 前缀：没有斜杠时 lastIndexOf 给 -1，slice(0) 就是原样 —— 写成一条无分支的
+  // 算式，因为 `split('/').pop() ?? namespace` 那个 `??` 的兜底只有类型层面存在，运行时永远
+  // 走不到，是量不到的分支。
+  const unscoped = namespace.slice(namespace.lastIndexOf('/') + 1);
+  const shortForm = unscoped.replace(/^docusaurus-/, '');
+  return (
+    pathForm.includes(`/${unscoped}/`) || pathForm.includes(`/${shortForm}/`)
+  );
+}
+
+/** 站点给本层的那份覆盖清单；顺带认出「写了覆盖但挂的槽位认不出本层」这一种手误。 */
+function findOverrideOrder(
+  slots: readonly {
+    name: string | undefined;
+    options: ApiFramePluginOptions | undefined;
+  }[],
+  warnings: string[],
+): string[] | undefined {
+  let orphanOrder: string[] | undefined;
+  for (const slot of slots) {
+    const order = slot.options?.themeConfig?.apiFrame?.order;
+    if (order === undefined) {
+      continue;
+    }
+    if (
+      slot.name !== undefined &&
+      slotIsNamespace(slot.name, IFRAME_NAMESPACE)
+    ) {
+      return order;
+    }
+    orphanOrder = order;
+  }
+  if (orphanOrder !== undefined) {
+    warnings.push(
+      `\`plugins\` 里有一项写了 \`${IFRAME_NAMESPACE}\` 的 \`themeConfig.apiFrame.order\` 覆盖，但它挂的那个插件名没被认成本层（路径写法要落在本包目录内）。覆盖未生效，仍按默认顺序判定。`,
+    );
+  }
+  return undefined;
+}
+
+/** 判定清单 + 需要提示给站点作者的落空原因。 */
+export type FrameDistribution = {
+  entries: readonly ApiFrameEntry[];
+  /** 每条都是「配置写了但没生效」的说明；页面级那几条带页面地址（去重按文本判等，不带地址会吞掉后面同毛病的页）。由 `DocItem` 在开发模式交给 `warnFrameDistribution`。 */
+  warnings: readonly string[];
+};
+
+export function resolveFrameDistribution(
+  plugins: readonly unknown[],
+  frontMatter: Record<string, unknown> | undefined,
+  pagePath?: string,
+): FrameDistribution {
+  const slots = plugins.map((plugin) => readPluginSlot(plugin));
+  const isInstalled = (namespace: string): boolean =>
+    slots.some(
+      (slot) =>
+        slot.name !== undefined && slotIsNamespace(slot.name, namespace),
+    );
+
+  const warnings: string[] = [];
+  const override = findOverrideOrder(slots, warnings);
+
+  let entries: ApiFrameEntry[];
+  if (override === undefined) {
+    entries = apiFrameEntriesOrdered().filter((entry) =>
+      isInstalled(entry.namespace),
+    );
+  } else {
+    entries = [];
+    for (const namespace of override) {
+      const entry = apiFrameByNamespace(namespace);
+      if (entry === undefined) {
+        warnings.push(
+          `覆盖清单里的 \`${namespace}\` 不在注册表内（拼错？），这一项被丢掉。`,
+        );
+        continue;
+      }
+      if (!isInstalled(namespace)) {
+        warnings.push(
+          `覆盖清单里的 \`${namespace}\` 没装（\`plugins\` 里没有这个名字），装机过滤对覆盖同样生效，这一层不参与判定。`,
+        );
+        continue;
+      }
+      if (!entries.includes(entry)) {
+        entries.push(entry);
+      }
+    }
+  }
+
+  // 键写了、层却没参与判定 —— 交回普通文档页之前，把原因留进 warnings（为什么要带页面地址见上面）。
+  for (const entry of apiFrameEntriesOrdered()) {
+    if (entries.includes(entry)) {
+      continue;
+    }
+    const value = frontMatter?.[entry.frontmatterKey];
+    if (typeof value === 'string' && value !== '') {
+      warnings.push(
+        `${pagePath ?? '这一页'} 写了 \`${entry.frontmatterKey}:\`，但 \`${entry.namespace}\` 没参与判定（${
+          isInstalled(entry.namespace) ? '被站点的覆盖清单排除' : '那个插件没装'
+        }），交回普通文档页。`,
+      );
+    }
+  }
+
+  return { entries, warnings };
+}
+
+/** 每种文本只打一次：配置级那几条（覆盖拼错、挂错槽位）每翻一页都会重算出来，逐页刷屏没有增量信息。 */
+const shownWarnings = new Set<string>();
+
+/** 把落空原因打到控制台：`DocItem` 只在开发模式调这一格，构建产物里不打。 */
+export function warnFrameDistribution(warnings: readonly string[]): void {
+  for (const warning of warnings) {
+    if (shownWarnings.has(warning)) {
+      continue;
+    }
+    shownWarnings.add(warning);
+    console.warn(`[theme-iframe] ${warning}`);
+  }
+}

package/lib/api-frame-messages.ts

@@ -0,0 +1,23 @@
+/**
+注册表那条层的消息约定，带缓存：`createFrameMessages` 每个命名空间只造一次，
+反复取是同一个引用（`useOuterFrameSync` / `useInnerFrameSync` 把它放在 effect 依赖里，
+引用换了就多一轮拆装监听器）。
+
+薄薄一层为什么单独成文件：`api-frame-registry.ts` 保持**纯数据**，配置期（node-bundle，
+没有 DOM）能类型检查；这一份引 `frame-messages.ts` 的形状，只给浏览器侧用。
+*/
+
+import type { FrameMessages } from './frame-messages.ts';
+import { createFrameMessages } from './frame-messages.ts';
+
+const frameMessagesCache = new Map<string, FrameMessages>();
+
+export function apiFrameMessages(namespace: string): FrameMessages {
+  const cached = frameMessagesCache.get(namespace);
+  if (cached) {
+    return cached;
+  }
+  const created = createFrameMessages(namespace);
+  frameMessagesCache.set(namespace, created);
+  return created;
+}

package/lib/api-frame-registry.ts

@@ -0,0 +1,101 @@
+/**
+「整页交给一个框」这一族层的注册表：一条层 = 一个条目，四条都在这一份里（`scalar` / `redoc`
+/ `stoplight` / `iframe`）。这里是层的**数据**来源（route、参数名、类名、命名空间），
+纯数据 + 纯函数、不引 React 不引浏览器：配置期（各包入口经工厂）与浏览器期（`DocItem`、框内
+那页）引同一份源码，那些名字不再像以前那样在编译边界两侧各写一份常量。带 `FrameMessages`
+的那份缓存归 `api-frame-messages.ts` —— 这一份必须能过 node-bundle（没有 DOM）的类型检查。
+
+判定的先后 = 这份清单的顺序（**默认值**，站点可覆盖、没装的层不判 —— 那一步在
+`api-frame-entries.ts`），语义与原层栈一致：越靠外的层先判自己的键。一页同写两把键时，
+排在前面那条赢。
+*/
+
+/** 条目共有的形状；两种 `kind` 差的格见下面两个类型。 */
+type ApiFrameEntryBase = {
+  /** 包名，同时是三条 postMessage 的命名空间与插件名。 */
+  namespace: string;
+  /** md frontmatter 里那条键，值就是框要渲染的地址。 */
+  frontmatterKey: string;
+  /**
+  外层 `<iframe>` 的**第二个**类名（第一个是共用的 `.api-frame`，尺寸与容器让位都在那一条上）。
+  这一格现在只用来认「这一格是哪一层赢的」，挂只属于一层的规则（如 stoplight 收页脚）。
+  */
+  frameClass: string;
+  /**
+  外层 `<iframe>` 的 `title` **兜底值**：页面写了 `frontMatter.title` 时优先用页面自己的
+  （`ApiFrame` 那一步），这一格是缺它时的可读名字。
+  */
+  title: string;
+};
+
+/** 框里是本包自己那条插件页面（同源），深链与亮暗靠 `frame-sync.ts` 那两条消息循环对齐。 */
+export type ApiFrameEntryInternal = ApiFrameEntryBase & {
+  kind: 'internal';
+  /** 框内那条页面的路径名（不带 `baseUrl`），由本包入口经 `addRoute` 注册。 */
+  route: string;
+  /** `component` 写 `@theme/` 下的别名（如 `'@theme/ScalarPage'`），经 `getThemePath()` 挂层。 */
+  pageComponent: string;
+  /** 框内地址里带 spec 地址的那一条查询参数名。 */
+  specParam: string;
+};
+
+/** 框里是**外部站点**（跨源）：没有那条通道，地址算法归用它的层自己管。 */
+export type ApiFrameEntryExternal = ApiFrameEntryBase & {
+  kind: 'external';
+};
+
+export type ApiFrameEntry = ApiFrameEntryInternal | ApiFrameEntryExternal;
+
+/** 这一族的清单（顺序 = 判定优先级，见文件头）。新增一条层的做法见 `docs/iframe-protocol.md`。 */
+const apiFrameEntries: readonly ApiFrameEntry[] = [
+  {
+    kind: 'internal',
+    namespace: '@show-docs/docusaurus-theme-scalar',
+    frontmatterKey: 'scalar',
+    route: 'scalar-view',
+    pageComponent: '@theme/ScalarPage',
+    specParam: 'src',
+    frameClass: 'scalar-frame',
+    title: 'API 文档',
+  },
+  {
+    kind: 'internal',
+    namespace: '@show-docs/docusaurus-theme-redoc',
+    frontmatterKey: 'redoc',
+    route: 'redoc-view',
+    pageComponent: '@theme/RedocPage',
+    specParam: 'src',
+    frameClass: 'redoc-frame',
+    title: 'API 文档',
+  },
+  {
+    kind: 'internal',
+    namespace: '@show-docs/docusaurus-theme-stoplight',
+    frontmatterKey: 'oas3',
+    route: 'stoplight-view',
+    pageComponent: '@theme/StoplightPage',
+    specParam: 'src',
+    frameClass: 'stoplight-frame',
+    title: 'API 文档',
+  },
+  {
+    kind: 'external',
+    namespace: '@show-docs/docusaurus-theme-iframe',
+    frontmatterKey: 'iframe',
+    frameClass: 'iframe',
+    title: '其他文档',
+  },
+];
+
+/** 按注册顺序遍历全部条目（`DocItem` 判键用的就是这个顺序）。 */
+export function apiFrameEntriesOrdered(): readonly ApiFrameEntry[] {
+  return apiFrameEntries;
+}
+
+/** 按包名取那一条层。取不到说明注册表里没有这一族 —— 调用方（入口工厂）应当立刻失败，
+而不是带着一条没人注册的路由继续跑。 */
+export function apiFrameByNamespace(
+  namespace: string,
+): ApiFrameEntry | undefined {
+  return apiFrameEntries.find((entry) => entry.namespace === namespace);
+}

package/lib/api-frame-theme.mts

@@ -0,0 +1,83 @@
+/**
+用 theme-iframe 承接外层套壳的**入口工厂**：三条 API 层的 `src/index.mts` 只需要带着自己的
+包名、产物目录与 webpack 差异来调它。
+
+它做三件事：`getThemePath()` 挂各包自己的层目录（里面只剩框内那条页面）、
+`contentLoaded` 按注册表把 `<route>` 页面注册上、其余一概不揽 —— webpack 的差异
+（Redoc 的 `worker_threads` 空模块、Elements 的样式表隔离与 polyfill）由调用方经
+`configureWebpack` 自己传，本工厂只负责把它接进 Plugin 形状。
+
+**配置期代码**：跑在 Node 里（jiti 直接吃这份 `.mts` 源码，扩展名按上游 lint preset 的口径
+标 Node 环境），不引 React、不引 DOM，
+类型引 `@docusaurus/types` 用 `import type`，浏览器那一份（`api-frame-registry.ts`）不会经过这里。
+*/
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { LoadContext, Plugin } from '@docusaurus/types';
+
+import {
+  apiFrameByNamespace,
+  type ApiFrameEntryInternal,
+} from './api-frame-registry.ts';
+
+export type ApiFrameThemeOptions = {
+  /** 包名，同时是注册表的键；表里没有这一族就直接失败。 */
+  namespace: string;
+  /**
+  入口产物所在目录（`dist/`）：`getThemePath()` 要按它算 `../theme`。
+  各包传自己那份 `import.meta.url`，`file:` 到路径的这一跳由工厂代做 ——
+  「产物在 dist/」这个假设收敛到一处，校验（下面 `existsSync`）也才有唯一的落点。
+  */
+  selfEntryUrl: string;
+  /** 本包独有的 webpack 差异；没有就不传（Scalar 就是没有）。 */
+  configureWebpack?: Plugin['configureWebpack'];
+};
+
+export function createApiFrameTheme(
+  context: LoadContext,
+  options: ApiFrameThemeOptions,
+): Plugin {
+  const { namespace, selfEntryUrl, configureWebpack } = options;
+
+  const entry = apiFrameByNamespace(namespace);
+  if (entry === undefined || entry.kind !== 'internal') {
+    throw new Error(
+      `@show-docs/docusaurus-theme-iframe 的注册表里没有 internal 层 ${namespace}：` +
+        '外层套壳由该注册表承接，新增层要先在那里登记一条。',
+    );
+  }
+  const view = entry satisfies ApiFrameEntryInternal;
+
+  // 层目录按「产物在 dist/、theme/ 站在包根」这一格算出来。它要是静默不存在，
+  // 症状隔着一层：@theme/XxxPage 解析不到、报错点在建站点那一步。当场验一次，
+  // 报**实际解析到的路径**——构建输出目录一改，这里立刻以抛错点名，而不是留个悬空别名。
+  const themePath = resolve(dirname(fileURLToPath(selfEntryUrl)), '../theme');
+  if (!existsSync(themePath)) {
+    throw new Error(
+      `${namespace} 的主题层目录不存在：${themePath}` +
+        '（由入口产物所在目录算出；若构建输出目录不再是 dist/，上一句 resolve 就是要改的地方）。',
+    );
+  }
+
+  return {
+    name: namespace,
+    // 主题层与 `components/` 是源码，站在包根上，不经 tsc：用本包的站点编译它们。
+    getThemePath() {
+      return themePath;
+    },
+    ...(configureWebpack !== undefined && { configureWebpack }),
+    contentLoaded({ actions }) {
+      // 框内那条独立页面：不是文档页、没有 frontmatter 可判，走官方插件路由 API。
+      // `component` 写 `@theme/` 别名 —— 打包器按别名找得到各包挂进层栈的那份页面，
+      // 站点那边的 swizzle 也还能覆写它。
+      actions.addRoute({
+        path: `${context.siteConfig.baseUrl.replace(/\/$/, '')}/${view.route}`,
+        component: view.pageComponent,
+        exact: true,
+      });
+    },
+  };
+}

package/lib/api-frame-view.tsx

@@ -0,0 +1,101 @@
+/**
+框内那一页的正文：三条 API 层共用这一份工厂 —— 外面那个框收成 `theme/DocItem` 一份套壳，
+框里这份收成这里。三处逐字相同的接线只留一份：按命名空间从注册表取本层那条 `internal` 条目
+（取不到就立刻抛）、按包名造那三条 postMessage 的名字、在工厂外面造好「把这一份文档的 `#`
+那一段报给外层」的函数（每次渲染换引用会让那条 effect 重装监听器）。
+
+各家差异只剩两格，都由调用方给：
+
+- `view`：这一层真正渲染文档的那份接线（各包 `components/` 里那份 UI），形状恒为 `url` +
+  `onRouteChange`。
+- 亮暗落到这一份文档的方式：`modeAttribute`（Redoc / Elements 写成 `<html>` 上一条属性）或
+  `onMode`（Scalar 换 `<body>` 上互斥的两个类名）。两格互斥，形状就是 `useInnerFrameSync`
+  那一条，本层不另设一套。
+
+两个方向怎么对齐、各家路由踩过的那些坑，记在 `docs/iframe-protocol.md` 与各层 `docs/internals.md`。
+
+## 产出的那一页是什么形状
+
+各包 `theme/XxxPage/index.tsx` 就是这份工厂的返回值，由本层插件路由（`addRoute` 注册的
+`@theme/XxxPage`）挂上。它**不是文档页**：frontmatter、面包屑、正文、目录、翻页都没有，整份
+文档就是给 iframe 装的那一格 —— 渲染器的运行时代码、它往 `<head>` 插的那张样式表、它的
+localStorage 与它自己的路由，全关在这份文档里，站点的文档页一行都碰不到。
+
+它也**不套** `@theme/Layout/Provider`：为什么不靠同源那条 localStorage 跟着站点开关翻，见
+`docs/iframe-protocol.md` 的「为什么不用框架的那条存储同步」一节。
+
+渲染只在浏览器里进行（`useIsBrowser` 那一格）：spec 地址在地址栏里，那份数据服务端根本没有，
+而渲染器在没有 DOM 的地方一跑就炸。各包 UI 组件因此不需要自己再挡一遍。
+*/
+
+import type { ComponentType, ReactNode } from 'react';
+
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+import { apiFrameMessages } from './api-frame-messages.ts';
+import { apiFrameByNamespace } from './api-frame-registry.ts';
+import { specUrlFromSearch } from './frame-messages.ts';
+import {
+  createRouteReporter,
+  useInnerFrameSync,
+  type InnerFrameSyncOptions,
+} from './frame-sync.ts';
+
+/** 三份渲染接线的共同形状：文档地址，加上「框内换了接口，报给外层」那一句。 */
+export type ApiFrameViewProps = {
+  /** 选中了哪条接口，报给框外那一份文档（就是下面那份 `createRouteReporter` 造的函数）。 */
+  onRouteChange: (hash: string) => void;
+  /** 要渲染的那份 OpenAPI 文档的地址（从框内那条地址的 `src` 参数里解出来）。 */
+  url: string;
+};
+
+/** `useInnerFrameSync` 的选项去掉 `messages`（那一份由命名空间造，不让调用方再写一遍）。 */
+type WithoutMessages<T> = T extends InnerFrameSyncOptions
+  ? Omit<T, 'messages'>
+  : never;
+
+export type ApiFrameViewConfig = WithoutMessages<InnerFrameSyncOptions> & {
+  /** 本层的包名：注册表里那一条的键，同时是三条 postMessage 的命名空间。 */
+  namespace: string;
+  /** 这一层渲染文档的那份接线（各包 `components/` 里那份 UI 组件）。 */
+  view: ComponentType<ApiFrameViewProps>;
+};
+
+/**
+造出框内那一页：接住外层送来的 `route` 与 `mode`，按地址里的 spec 参数渲染，
+并把渲染器换过的那一段报回外层。
+
+地址里那一段缺着、或写成非 http(s) 的，这一格什么都不渲染 —— 那条页面是条公开地址，
+别人直接打开它时，渲染器自己那份「加载失败」摆在正文区，观感反而更像坏了。
+*/
+export function createApiFrameView(config: ApiFrameViewConfig): ComponentType {
+  const { namespace, view: View, ...syncOptions } = config;
+
+  const entry = apiFrameByNamespace(namespace);
+  if (entry === undefined || entry.kind !== 'internal') {
+    throw new Error(`注册表里缺 ${namespace}`);
+  }
+
+  const messages = apiFrameMessages(namespace);
+  const reportRouteToParent = createRouteReporter(messages);
+
+  return function ApiFrameView(): ReactNode {
+    const isBrowser = useIsBrowser();
+
+    useInnerFrameSync({ ...syncOptions, messages });
+
+    if (!isBrowser) {
+      return null;
+    }
+
+    const url = specUrlFromSearch(
+      window.location.search,
+      window.location.origin,
+      entry.specParam,
+    );
+
+    return url === undefined ? null : (
+      <View onRouteChange={reportRouteToParent} url={url} />
+    );
+  };
+}

package/lib/frame-messages.ts

@@ -0,0 +1,158 @@
+/**
+外层文档页与框内那一页之间的约定：iframe 的地址怎么拼、那三条 postMessage 长什么样。
+
+两边都是站点编译的本仓代码，跑在**同一个源**里（框内那一页是站点自己的一条插件路由），所以这套
+约定不需要跨源信任；每条消息仍要过 {@link isTrustedMessage} 那道校验 —— 为的是别人往这一页
+postMessage 时不会被当成自家的，而不是为了防自己。
+
+这一份只有**约定与形状**，没有 React、也没有 DOM；两条消息循环在 `frame-sync.ts`，框那一格与
+它的共用版式在 `components/api-frame.tsx` 与 `components/api-frame.css`。
+*/
+
+/** 亮暗那一格的取值。形状与站点的开关相同，但**不引**它的类型：那条属性由外层送进来。 */
+export type FrameColorMode = 'light' | 'dark';
+
+export type FrameRouteMessage = { type: string; hash: string };
+export type FrameReadyMessage = { type: string };
+export type FrameModeMessage = {
+  type: string;
+  mode: FrameColorMode;
+};
+
+/** 一个命名空间对应的一份消息约定，见 {@link createFrameMessages}。 */
+export type FrameMessages = {
+  /** 外层 → 框内：外层地址栏里 `#` 那一段（选中了哪条接口）。 */
+  route(hash: string): FrameRouteMessage;
+  /** 框内 → 外层：框里那份文档起来了，向外层要地址与模式。 */
+  ready(): FrameReadyMessage;
+  /** 外层 → 框内：站点当前是亮色还是暗色。 */
+  mode(mode: FrameColorMode): FrameModeMessage;
+  /** 收到的数据是不是那一条接口地址（只看形状，来源由 {@link isTrustedMessage} 判）。 */
+  isRoute(data: unknown): data is FrameRouteMessage;
+  /** 收到的数据是不是「框里起来了」那一条（只看形状）。 */
+  isReady(data: unknown): data is FrameReadyMessage;
+  /** 收到的数据是不是「站点换亮暗了」那一条（只看形状）。 */
+  isMode(data: unknown): data is FrameModeMessage;
+};
+
+/**
+按命名空间造一份消息约定。
+
+命名空间取用它的主题包的包名（例如 `@show-docs/docusaurus-theme-redoc`），三条 `type`
+就是 `<命名空间>/route`、`/ready`、`/mode`。三条层各用各的命名空间，因此**不会**互相
+认到对方的消息 —— 同一站点同时挂三份文档时，这一格是必需的。
+*/
+export function createFrameMessages(namespace: string): FrameMessages {
+  const routeType = `${namespace}/route`;
+  const readyType = `${namespace}/ready`;
+  const modeType = `${namespace}/mode`;
+
+  return {
+    route: (hash) => ({ type: routeType, hash }),
+    ready: () => ({ type: readyType }),
+    mode: (mode) => ({ type: modeType, mode }),
+
+    isReady: (data): data is FrameReadyMessage =>
+      typeof data === 'object' &&
+      data !== null &&
+      (data as Partial<FrameReadyMessage>).type === readyType,
+
+    // `hash` 只认空串与 `#` 开头的那些：拿到别的东西就当不是自家消息，
+    // 而不是照原样往地址里塞。
+    isRoute: (data): data is FrameRouteMessage => {
+      if (typeof data !== 'object' || data === null) {
+        return false;
+      }
+      const message = data as Partial<FrameRouteMessage>;
+      return (
+        message.type === routeType &&
+        typeof message.hash === 'string' &&
+        (message.hash === '' || message.hash.startsWith('#'))
+      );
+    },
+
+    // 亮暗只认这两个值：地址栏与第三方脚本都能往这一页送形状对上的对象，取值不在这两格
+    // 就不往 `<html>` 上写。
+    isMode: (data): data is FrameModeMessage => {
+      if (typeof data !== 'object' || data === null) {
+        return false;
+      }
+      const message = data as Partial<FrameModeMessage>;
+      return (
+        message.type === modeType &&
+        (message.mode === 'light' || message.mode === 'dark')
+      );
+    },
+  };
+}
+
+/**
+拼框内那一页的地址。
+
+`specUrl` 编码进去，`hash` **不**放进去：iframe 的 `src` 因此只跟 frontmatter 走，服务端与
+客户端算出的完全一样，两边不会在 `src` 这一格上对不上。深链那一段与亮暗模式都靠消息送，
+见 {@link createFrameMessages}。
+*/
+export function frameViewSrc(options: {
+  baseUrl: string;
+  route: string;
+  specParam: string;
+  specUrl: string;
+}): string {
+  const query = new URLSearchParams({ [options.specParam]: options.specUrl });
+  return `${options.baseUrl}${options.route}?${query}`;
+}
+
+/**
+从框内那一页的地址里取出要渲染的 spec 地址。
+
+只认能解析成 `http:` / `https:` 的：这一格来自地址栏，任何人都能手工拼一条
+`/redoc-view?src=javascript:…` 那样的地址，而渲染器拿到的是「去取这个地址」的指令，
+不该由本层替它把非 URL 的东西喂进去。解析结果恒为绝对地址，`/openapi.yaml` 这种相对写法
+按 `base`（调用方给 `window.location.origin`）展开。
+*/
+export function specUrlFromSearch(
+  search: string,
+  base: string,
+  specParam: string,
+): string | undefined {
+  const raw = new URLSearchParams(search).get(specParam);
+  if (raw === null) {
+    return undefined;
+  }
+  try {
+    const url = new URL(raw, base);
+    return url.protocol === 'http:' || url.protocol === 'https:'
+      ? url.href
+      : undefined;
+  } catch {
+    // `base` 本身不是合法 URL 时才走到这里（拼错的相对地址在 `new URL` 那一格抛）
+    return undefined;
+  }
+}
+
+/**
+`iframe:` 那一层嵌**外部站点**时，frontmatter 那个值要落成的最终地址：`/` 打头补上 origin、
+`?path=` 再解一层，两格都没有就原样。
+
+`?path=` 由 `URLSearchParams` 自动解码，`src` 从 frontmatter 来、本来就是明文，所以收尾
+**不再**对整串做二次解码 —— 旧写法那样会把地址里合法的 `%` 序列解坏（`a=%25` 变成 `a=%`、
+`/a%2Fb` 变成 `/a/b`）。
+
+`origin` 由调用方给（浏览器里就是 `window.location.origin`），与 {@link specUrlFromSearch}
+同形状：这一份没有 DOM，配置期那条链路也引得到它。服务端渲染阶段拿不到窗口，调用方直接用
+frontmatter 里的原值，不等这一步。
+*/
+export function externalFrameURL(options: {
+  src: string;
+  search: string;
+  origin: string;
+}): string {
+  const path = new URLSearchParams(options.search).get('path') ?? '';
+
+  const resolved = options.src.startsWith('/')
+    ? new URL(options.src, options.origin).href
+    : options.src;
+
+  return path === '' ? resolved : new URL(path, resolved).href;
+}

package/lib/frame-sync.ts

@@ -0,0 +1,219 @@
+import { useEffect } from 'react';
+import type { RefObject } from 'react';
+
+import type { FrameColorMode, FrameMessages } from './frame-messages.ts';
+
+/**
+那两条消息循环：外层那份文档里的一个 iframe，与框内那份文档里的渲染器。
+
+两边各装各的监听器，谁先谁后不固定，所以对齐是**两侧各推一次**的：框里起来时问一句
+（{@link useInnerFrameSync} 里那句 ready），外层装好监听器也主动推一次
+（{@link useOuterFrameSync}）。只守其中一条就丢得掉 —— 实测丢过一次：`page.reload()` 之后
+框里那句 ready 先发出、外层的监听器还没装上，于是深链与模式都没送进去。
+
+这里不含 iframe 那一格本身，也不含它的尺寸：调用方自己渲染 `<iframe ref={…}>`，把同一个 ref
+交给 {@link useOuterFrameSync}。
+*/
+
+/** 外层那个 iframe 的 ref，与调用方渲染时挂的是同一个。 */
+export type FrameRef = RefObject<HTMLIFrameElement | null>;
+
+/**
+这条消息是不是从 `expectedSource` 那个窗口、同一个源发来的。两个方向都过这一格：外层只收自己
+那个 iframe 的，框内只收装载它的父窗口的 —— 别人手工拼进地址栏的那一条、页面上第三方脚本发的
+消息都进不来。
+
+引 DOM 类型的只有这一份文件：注册表那条链不碰 `Window`，配置期与浏览器期因此能共用同一份源码。
+*/
+export function isTrustedMessage(
+  event: MessageEvent,
+  expectedSource: Window | null,
+  origin: string,
+): boolean {
+  return event.source === expectedSource && event.origin === origin;
+}
+
+/**
+挂在**外层**那份文档里：把地址栏那一段与当前亮暗模式送进框里，并接住框里报回来的那一段。
+
+- 外层 → 框内：`route` 与 `mode` 两条。装好监听器先推一次，`colorMode` 每次变化再推一次
+  （外层点了亮暗开关，框里不会来问第二次）。
+- 框内 → 外层：`ready`（于是再推一次）与 `route`。后者只换外层地址里 `#` 那一段，
+  而且是**替换**当前那条历史记录：框里点一条接口不该在浏览器历史里多出一格，
+  那会让「后退」变成在同一页的两条接口之间来回走。
+- 前进/后退改的是外层地址（深链那一段就在里面），把它送进框里，两边才还是同一条接口。
+*/
+export function useOuterFrameSync(options: {
+  frameRef: FrameRef;
+  messages: FrameMessages;
+  colorMode: FrameColorMode;
+}): void {
+  const { frameRef, messages, colorMode } = options;
+
+  useEffect(() => {
+    const frame = frameRef.current;
+    if (frame === null) {
+      return undefined;
+    }
+    const { origin } = window.location;
+
+    const postRoute = (target: Window): void => {
+      target.postMessage(messages.route(window.location.hash), origin);
+    };
+
+    const postMode = (target: Window): void => {
+      target.postMessage(messages.mode(colorMode), origin);
+    };
+
+    // 框里那份是不是已经站在同一个源上，是的话把它交出去。还没开始加载时它是 `about:blank`，
+    // 那里的 origin 是字符串 `null`，送过去只会被浏览器按目标源丢掉、白刷一条控制台报错；读
+    // `location` 只在同源时不抛，抛了就当还没起来。同源的判定只做一次并交出那个窗口，而不是
+    // 每格各判一次再 `?.` —— 「判过同源之后 contentWindow 又变空」在同步代码里不发生，
+    // 那条可选链就是永远量不到的分支。
+    const isFrameLoaded = (): Window | undefined => {
+      try {
+        return frame.contentWindow?.location.origin === origin
+          ? frame.contentWindow
+          : undefined;
+      } catch {
+        return undefined;
+      }
+    };
+
+    const pushToFrame = (): void => {
+      const target = isFrameLoaded();
+      if (target === undefined) {
+        return;
+      }
+      postRoute(target);
+      postMode(target);
+    };
+
+    const onMessage = (event: MessageEvent): void => {
+      if (!isTrustedMessage(event, frame.contentWindow, origin)) {
+        return;
+      }
+      if (messages.isReady(event.data)) {
+        pushToFrame();
+        return;
+      }
+      if (
+        !messages.isRoute(event.data) ||
+        event.data.hash === window.location.hash
+      ) {
+        return;
+      }
+      window.history.replaceState(
+        null,
+        '',
+        `${window.location.pathname}${window.location.search}${event.data.hash}`,
+      );
+    };
+
+    // 前进/后退时框可能还没站到同源上（或已经被摘掉）：走同一条同源判定，而不是赌
+    // contentWindow 一定在。
+    const onPopState = (): void => {
+      const target = isFrameLoaded();
+      if (target !== undefined) {
+        postRoute(target);
+      }
+    };
+
+    window.addEventListener('message', onMessage);
+    window.addEventListener('popstate', onPopState);
+    pushToFrame();
+    return () => {
+      window.removeEventListener('message', onMessage);
+      window.removeEventListener('popstate', onPopState);
+    };
+  }, [colorMode, frameRef, messages]);
+}
+
+/**
+挂在**框内**那份文档里：起来第一件事向外层要那两格，之后接住外层送来的两条。
+
+- `mode`：落到这一份文档自己身上，落法由各层给（见 {@link InnerFrameSyncOptions} 那两条）。
+  这一份文档不套 `ColorModeProvider`，站点那条 `data-theme` 在这里只是内联脚本写死的一份、
+  没人维护，所以本层不读它。第一次送达之前是空的、也就是亮色（本站默认亮色，送达不靠谁先起来
+  —— 两边各推一次）；站点把默认改成暗色时，这一格会先亮一下再翻过去。
+- `route`：改 `window.location.hash`，这一步触发 `hashchange`，于是换到那条接口而整份文档不
+  重新加载。渲染器认不认这一格是各家的事（Redoc 与 Elements 的路由按它走，Scalar 只听
+  `popstate`，转换写在那一层的 `scalar-ui.tsx`）。整页加载一条深链时那一段也是这么进来的。
+
+反方向（框内 → 外层）**不在这里**，理由见 {@link createRouteReporter}。
+*/
+export type InnerFrameSyncOptions = { messages: FrameMessages } & (
+  | {
+      /** 写成这一份文档 `<html>` 上一条属性（属性名由调用方给）：按属性判亮暗的那两家。 */
+      modeAttribute: string;
+      onMode?: undefined;
+    }
+  | {
+      /** 落法整个交给调用方：Scalar 换的是 `<body>` 上互斥的两个类名，属性名换不动它。 */
+      modeAttribute?: undefined;
+      onMode: (mode: FrameColorMode) => void;
+    }
+);
+
+export function useInnerFrameSync(options: InnerFrameSyncOptions): void {
+  const { messages, modeAttribute, onMode } = options;
+
+  useEffect(() => {
+    const { origin } = window.location;
+
+    const onMessage = (event: MessageEvent): void => {
+      if (!isTrustedMessage(event, window.parent, origin)) {
+        return;
+      }
+      if (messages.isMode(event.data)) {
+        if (onMode) {
+          onMode(event.data.mode);
+          return;
+        }
+        // 走到这一格就说明上面那条没给，类型上 `modeAttribute` 必在 —— 但解构出来的两个成员
+        // 不会跟着 `options` 一起收窄，所以要这一句转述（不是运行期的兜底）。
+        document.documentElement.setAttribute(
+          modeAttribute as string,
+          event.data.mode,
+        );
+        return;
+      }
+      if (
+        !messages.isRoute(event.data) ||
+        event.data.hash === window.location.hash
+      ) {
+        return;
+      }
+      // 空串这一格浏览器处理成「把 `#` 整段去掉」，不是「跳到一个空 id 的元素」
+      window.location.hash = event.data.hash;
+    };
+
+    window.addEventListener('message', onMessage);
+    window.parent.postMessage(messages.ready(), origin);
+    return () => {
+      window.removeEventListener('message', onMessage);
+    };
+  }, [messages, modeAttribute, onMode]);
+}
+
+/**
+造一个「把这一份文档地址里那一段报给外层」的函数（框内 → 外层那一条）。
+
+为什么由调用方在渲染器换接口的时候报，而不是这里监听 `hashchange`：三个渲染器（Redoc 的路由、
+Elements 的路由、Scalar 自己那一条）换地址走的都是 `history.pushState`，那个方法**不触发**
+`hashchange`（那个事件只由改 `location.hash`、点锚点链接、前进/后退这几条路触发）。实测都是这条：
+框里点一条接口，`location.hash` 变了、渲染器认到了，`hashchange` 一次都没进来。
+
+**挂载那一次调用方别报**：那一次报的是初始位置 `#/`，而外层可能正带着一条深链
+（`/redoc-demo#/orders/createorder`），初始那一句会先把外层地址栏里那一段擦成 `#/`，紧接着外层
+补送深链时读到的已经是被擦过的值，深链就丢了。两家 `LocationMirror` 里那格 `first` 钉的就是这一条。
+
+返回的函数只读 `window`，调用方可以在模块级造一份稳定的，不必每次渲染新建。
+*/
+export function createRouteReporter(
+  messages: FrameMessages,
+): (hash: string) => void {
+  return (hash: string): void => {
+    window.parent.postMessage(messages.route(hash), window.location.origin);
+  };
+}

package/lib/index.ts

@@ -0,0 +1,6 @@
+export * from './frame-messages.ts';
+export * from './frame-sync.ts';
+export * from './api-frame-registry.ts';
+export * from './api-frame-messages.ts';
+export * from './api-frame-entries.ts';
+export * from './api-frame-view.tsx';

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@show-docs/docusaurus-theme-iframe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Md 的 frontmatter 写 iframe: <目标 URL> 时把该页整页换成那个页面",
+  "keywords": [],
+  "homepage": "https://github.com/show-docs/docusaurus/tree/master/theme/theme-iframe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/show-docs/docusaurus.git",
+    "directory": "theme/theme-iframe"
+  },
+  "bugs": {
+    "url": "https://github.com/show-docs/docusaurus/issues"
+  },
+  "types": "dist/index.d.mts",
+  "main": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "default": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./lib/*": "./lib/*"
+  },
+  "files": [
+    "components",
+    "dist",
+    "lib",
+    "theme"
+  ],
+  "type": "module",
+  "peerDependencies": {
+    "@docusaurus/types": "^3.10.2",
+    "react": "~18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@docusaurus/types": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
 }

package/theme/DocItem/index.tsx

@@ -0,0 +1,65 @@
+import DocItem from '@theme-prev/DocItem';
+
+import type { ComponentType, ReactNode } from 'react';
+
+import { useLocation } from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+import { ApiFrame } from '../../components/api-frame.tsx';
+import {
+  resolveFrameDistribution,
+  warnFrameDistribution,
+} from '../../lib/api-frame-entries.ts';
+
+// 命中与否只看 frontmatter 里那几条已注册的键（值就是框要渲染的地址），
+// 键的形状由注册表给出，本层不再逐包声明。
+type MDXContent = ComponentType<Record<string, unknown>> & {
+  frontMatter?: Record<string, unknown>;
+};
+
+type Props = { content?: MDXContent };
+
+/**
+本层是「整页交给一个框」这一族的**唯一外层套壳**：拿 `resolveFrameDistribution()` 给出的清单
+判 frontmatter（顺序、装机过滤与站点覆盖那一条规则都住在 `lib/api-frame-entries.ts`，这里不抄
+第二份），命中就把**整个 `DocItem`** 换成通用框 —— 与收拢前四条层同一落点、同一取舍；落空那份
+`warnings` 只在开发模式交给 `warnFrameDistribution()` 打。
+
+代价是官方 `DocItem` 里的东西一并不要：`DocProvider`、`DocItem/Metadata`（页面标题与
+描述因此退回站点名）、`DocItem/Layout`（面包屑、正文外壳、翻页、右侧目录）。剩下的是
+文档页那层壳：navbar、footer，还有包着 iframe 的那个 `.container`。
+
+三条 API 层的包因此**不再有 `theme/DocItem`**：它们交出命名空间，框里那条页面仍由各自的入口
+注册（`lib/api-frame-theme.mts` 那份工厂）。
+*/
+export default function DocItemFrame(props: Props): ReactNode {
+  const frontMatter = props.content?.frontMatter;
+  const { siteConfig } = useDocusaurusContext();
+  const { pathname } = useLocation();
+
+  const { entries, warnings } = resolveFrameDistribution(
+    siteConfig.plugins,
+    frontMatter,
+    pathname,
+  );
+
+  if (process.env.NODE_ENV === 'development') {
+    warnFrameDistribution(warnings);
+  }
+
+  for (const entry of entries) {
+    const value = frontMatter?.[entry.frontmatterKey];
+    if (typeof value === 'string' && value !== '') {
+      return (
+        <ApiFrame
+          entry={entry}
+          value={value}
+          frontMatterTitle={frontMatter?.title}
+        />
+      );
+    }
+  }
+
+  // 没命中时本层等于透明：整个交回下层实现。
+  return <DocItem {...props} />;
+}