@aalis/api-webui 0.11.0 → 0.12.0

package/dist/frame/frame.css

@@ -0,0 +1,218 @@
+/*
+ * 插件前端的样式基线，托管为 /frames/_base/frame.css，插件前端可选引用：
+ *   <link rel="stylesheet" href="/frames/_base/frame.css">
+ * 只给元素级的样式，不设按类名选的变体。颜色只引用主题令牌（助手收到 init 时写在根元素上，主题变了跟着更新）；
+ * 尺寸写在本文件里，取值与宿主界面相同，触屏与减少动效由本文件自己的媒体查询求值。圆角用 --radius-sm、--radius-md
+ * 两个名字写默认值，宿主以后推入的值写在根元素的内联样式上，盖过这里的默认值。
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+:root {
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  font-family:
+    system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC",
+    sans-serif;
+  font-size: 100%;
+  line-height: 1.375rem;
+  color: var(--color-text);
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  padding: 1rem;
+  font-size: 0.875rem;
+  background: var(--color-bg);
+}
+
+h1,
+h2,
+h3 {
+  margin: 0 0 0.5rem;
+  font-size: 1rem;
+  font-weight: 600;
+  line-height: 1.5rem;
+}
+
+p,
+ul,
+ol,
+table,
+pre {
+  margin: 0 0 0.75rem;
+}
+
+ul,
+ol {
+  padding-left: 1.5rem;
+}
+
+li + li {
+  margin-top: 0.25rem;
+}
+
+a {
+  color: var(--color-accent-text);
+  text-decoration: underline 1px;
+  text-underline-offset: 2px;
+}
+
+/* 焦点环用 outline：Windows 高对比度模式会去掉阴影 */
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+/* 按钮只有一种，与宿主的次要按钮一致 */
+button {
+  min-width: 1.75rem;
+  min-height: 1.75rem;
+  padding: 0 0.5rem;
+  border: 0;
+  border-radius: var(--radius-sm);
+  font-size: 0.8125rem;
+  font-weight: 400;
+  line-height: 1.25rem;
+  background: var(--color-fill-2);
+  cursor: pointer;
+  transition: background-color 100ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+/* 只写底色：简写 background 会复位 background-clip，触屏上底色就铺进透明边框（见文件末尾） */
+button:hover:not(:disabled) {
+  background-color: var(--color-fill-3);
+}
+
+button:disabled {
+  color: var(--color-text-disabled);
+  cursor: default;
+}
+
+input:not([type="checkbox"]):not([type="radio"]),
+select,
+textarea {
+  min-height: 1.75rem;
+  padding: 0 0.75rem;
+  font-size: 0.875rem;
+  background: transparent;
+  border: 1px solid var(--color-border-control);
+  border-radius: var(--radius-sm);
+}
+
+textarea {
+  padding: 0.5rem 0.75rem;
+}
+
+input:focus-visible,
+select:focus-visible,
+textarea:focus-visible {
+  outline-offset: 0;
+}
+
+::placeholder {
+  color: var(--color-text-3);
+}
+
+input[type="checkbox"],
+input[type="radio"] {
+  accent-color: var(--color-accent);
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.8125rem;
+  line-height: 1.25rem;
+}
+
+th,
+td {
+  height: 2.25rem;
+  padding: 0 0.75rem;
+  border-bottom: 1px solid var(--color-border);
+  text-align: left;
+}
+
+th {
+  height: 2rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--color-text-2);
+}
+
+code,
+kbd,
+pre {
+  font-family: ui-monospace, "SF Mono", "JetBrains Mono", "Cascadia Mono", Menlo, Consolas, monospace;
+}
+
+:not(pre) > code {
+  padding: 0 0.25rem;
+  border-radius: var(--radius-sm);
+  font-size: 0.9em;
+  background: var(--color-fill-2);
+}
+
+pre {
+  padding: 0.75rem;
+  overflow-x: auto;
+  border-radius: var(--radius-md);
+  font-size: 0.8125rem;
+  line-height: 1.25rem;
+  background: var(--color-fill-1);
+}
+
+/*
+ * 触屏：点按范围 44 像素。按钮外面一圈 0.25rem 的透明边框占排版位置，底色只画到边框以内，看得见的是 36 像素；
+ * 圆角加上边框宽，里面的角仍是 --radius-sm；焦点环往回收到看得见的框外 2 像素。
+ * 输入框 44 像素高，字号不小于 16 像素，免得 iOS 聚焦时放大整页
+ */
+@media (pointer: coarse) {
+  button {
+    min-width: 2.75rem;
+    min-height: 2.75rem;
+    border: 0.25rem solid transparent;
+    border-radius: calc(var(--radius-sm) + 0.25rem);
+    background-clip: padding-box;
+  }
+
+  button:focus-visible {
+    outline-offset: -2px;
+  }
+
+  input:not([type="checkbox"]):not([type="radio"]),
+  select {
+    min-height: 2.75rem;
+  }
+
+  input:not([type="checkbox"]):not([type="radio"]),
+  select,
+  textarea {
+    font-size: 1rem;
+  }
+
+  td {
+    height: 3rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  button {
+    transition: none;
+  }
+}

package/dist/frame/frame.js

@@ -0,0 +1,100 @@
+// 插件前端的助手，托管为 /frames/_base/frame.js。片段里的 nonce 原样读出、不清：清片段会往会话历史里加条目，
+// nonce 对框架自己本来也不保密。同一页上的框架都是不透明来源、能互相发窗口消息，但只有父文档发得出来源是
+// window.parent 的消息，所以只认来自它、带端口的第一个 init，之后只用这个端口。主题令牌在收到 init 的同一拍写上，
+// 框架显示出来时已是宿主的配色
+/** 与 api-webui 的 FRAME_PROTOCOL_VERSION 同值：助手随 api-webui 同版本发布 */
+const PROTOCOL = '1.0';
+/** 发出 hello 之后等 init 的时长 */
+const INIT_TIMEOUT_MS = 10_000;
+function applyTheme({ kind, tokens }) {
+    const root = document.documentElement;
+    for (const [name, value] of Object.entries(tokens))
+        root.style.setProperty(name, value);
+    root.dataset.theme = kind;
+    root.style.colorScheme = kind;
+}
+function connected(port, sessionId) {
+    const pending = new Map();
+    const invalidated = new Set();
+    const changed = new Set();
+    let lastId = 0;
+    const send = (message) => port.postMessage(message);
+    function request(message) {
+        lastId += 1;
+        const id = lastId;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+            send({ ...message, id });
+        });
+    }
+    function listen(listeners, listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    port.onmessage = ({ data }) => {
+        if (data.type === 'result') {
+            const waiting = pending.get(data.id);
+            pending.delete(data.id);
+            if (data.ok)
+                waiting?.resolve(data.value);
+            else
+                waiting?.reject(Object.assign(new Error(data.error.message), { code: data.error.code }));
+        }
+        else if (data.type === 'theme') {
+            applyTheme(data);
+        }
+        else if (data.type === 'invalidate') {
+            for (const listener of invalidated)
+                listener(data.source);
+        }
+        else if (data.type === 'sessions.changed') {
+            for (const listener of changed)
+                listener({ upserts: data.upserts, removes: data.removes });
+        }
+    };
+    addEventListener('pagehide', () => send({ type: 'leaving' }));
+    return {
+        sessionId,
+        data: (source, input) => request({ type: 'data', source, ...(input && { input }) }),
+        action: (action, input) => request({ type: 'action', action, ...(input && { input }) }),
+        open: async (target) => {
+            await request({ type: 'open', target });
+        },
+        onInvalidate: listener => listen(invalidated, listener),
+        listSessions: params => request({ type: 'sessions.list', ...params }),
+        onSessionsChanged: listener => listen(changed, listener),
+        abortTurn: async (params) => {
+            await request({ type: 'turn.abort', ...params });
+        },
+    };
+}
+function handshake() {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            removeEventListener('message', onInit);
+            reject(new Error('宿主没有回应握手'));
+        }, INIT_TIMEOUT_MS);
+        function onInit(event) {
+            if (event.source !== parent || event.ports.length !== 1 || event.data?.type !== 'init')
+                return;
+            removeEventListener('message', onInit);
+            clearTimeout(timer);
+            const { theme, sessionId } = event.data;
+            if (typeof theme?.tokens !== 'object' || theme.tokens === null) {
+                reject(new Error('宿主的 init 不合格：theme 要是带 tokens 的对象'));
+                return;
+            }
+            applyTheme(theme);
+            resolve(connected(event.ports[0], sessionId));
+        }
+        addEventListener('message', onInit);
+        const hello = { type: 'hello', protocol: PROTOCOL, nonce: location.hash.slice(1) };
+        parent.postMessage(hello, '*');
+    });
+}
+let connection;
+/** 与宿主握手，拿到这一页的连接；调多次是同一个连接 */
+export function connect() {
+    connection ??= handshake();
+    return connection;
+}

package/dist/frame.d.ts

@@ -0,0 +1,165 @@
+import type { SessionMethodParams, SessionMethodResult, SessionNotificationParams } from '@aalis/api-session-protocol';
+import type { ThemeKind, ThemeToken } from './theme.js';
+/** 消息通道的协议版本 `<主>.<次>`：握手时主版本不同，宿主卸载框架 */
+export declare const FRAME_PROTOCOL_VERSION = "1.0";
+/**
+ * 框架的沙箱值：宿主 iframe 的 sandbox 属性与框架文件响应头 CSP 的 sandbox 指令同一份。只给脚本，
+ * 不给 allow-same-origin（与 allow-scripts 同给时框架能自己摘掉沙箱），也不给表单、弹窗、原生对话框、顶层跳转与下载
+ */
+export declare const FRAME_SANDBOX = "allow-scripts";
+/**
+ * 宿主数据能力的词表，封闭集合，按加法扩：
+ * - `sessions:read`：读会话树与状态（请求 `sessions.list`，挂载起收到 `sessions.changed`）；
+ * - `turn:abort`：停止会话的回合（请求 `turn.abort`）。
+ * 申请了的框架与 owner 自己的界面看得一样多，不按会话收窄
+ */
+export declare const FRAME_HOST_CAPABILITIES: readonly ["sessions:read", "turn:abort"];
+export type FrameHostCapability = (typeof FRAME_HOST_CAPABILITIES)[number];
+/** 名字（数据源名、动作名）最多这么多个字符 */
+export declare const FRAME_NAME_MAX_LENGTH = 128;
+/** 标识（会话 id、回合 id、翻页游标、握手的随机数）最多这么多个字符 */
+export declare const FRAME_ID_MAX_LENGTH = 256;
+/** 地址最多这么多个字符 */
+export declare const FRAME_URL_MAX_LENGTH = 2048;
+/** 握手：nonce 是宿主放在框架地址片段里的随机数 */
+export interface FrameHello {
+    type: 'hello';
+    protocol: string;
+    nonce: string;
+}
+/** 取这一页一个数据源的数据：数据源名与输入由宿主照原样交给服务端核 */
+export interface FrameDataRequest {
+    type: 'data';
+    id: number;
+    source: string;
+    input?: Record<string, unknown>;
+}
+/** 调这一页的一个动作：destructive 的先由宿主弹确认框，框里按输入字段列出这次的值 */
+export interface FrameActionRequest {
+    type: 'action';
+    id: number;
+    action: string;
+    input?: Record<string, unknown>;
+}
+/** 请宿主打开：外站地址（只许 http、https，与宿主同源的不收）经宿主的对话框由用户点开；会话在应用内打开 */
+export interface FrameOpenRequest {
+    type: 'open';
+    id: number;
+    target: {
+        url: string;
+    } | {
+        session: string;
+    };
+}
+/** 列会话（要 sessions:read）：只透传会话协议 sessions/list 的这四个参数 */
+export type FrameSessionsListRequest = {
+    type: 'sessions.list';
+    id: number;
+} & Pick<SessionMethodParams<'sessions/list'>, 'parentId' | 'archived' | 'cursor' | 'limit'>;
+/** 停止一个会话的回合（要 turn:abort）：参数同会话协议的 turn/abort */
+export type FrameTurnAbortRequest = {
+    type: 'turn.abort';
+    id: number;
+} & SessionMethodParams<'turn/abort'>;
+/** 框架文档正在被替换（离开了宿主给它的地址）：宿主立即卸载，不回 */
+export interface FrameLeaving {
+    type: 'leaving';
+}
+/** 框架发的请求 */
+export type FrameRequest = FrameDataRequest | FrameActionRequest | FrameOpenRequest | FrameSessionsListRequest | FrameTurnAbortRequest;
+/** 框架经端口发的消息 */
+export type FrameMessage = FrameRequest | FrameLeaving;
+/**
+ * 请求失败的原因，封闭集合：
+ * - `invalid`：消息或输入不对（转发的 HTTP 400、414、431）；
+ * - `denied`：没申请的能力；这个框架已开着一个宿主对话框时，再请求外链或要确认的动作；
+ * - `not-found`：页面、会话、数据源或动作不在（HTTP 404）；
+ * - `busy`：超出在途上限；
+ * - `cancelled`：用户在宿主的确认框或外链对话框里取消；
+ * - `unavailable`：会话服务不在、连接断开（HTTP 503 与连不上）；
+ * - `failed`：插件的处理函数或宿主服务出错（其余 4xx 与 5xx），message 写原因。
+ */
+export type FrameErrorCode = 'invalid' | 'denied' | 'not-found' | 'busy' | 'cancelled' | 'unavailable' | 'failed';
+/** 当前主题：深浅与主题令牌的值（THEME_TOKENS 里的名字到值）。尺寸不传，框架在同一个浏览器里自己求值 */
+export interface FrameTheme {
+    kind: ThemeKind;
+    tokens: Record<ThemeToken, string>;
+}
+/** 握手时随端口交出；sessionId 只给会话面板，换会话时宿主重新挂载 */
+export interface FrameInit {
+    type: 'init';
+    protocol: string;
+    experimental: true;
+    sessionId?: string;
+    theme: FrameTheme;
+}
+/** 回一个请求 */
+export type FrameResult = {
+    type: 'result';
+    id: number;
+} & ({
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        code: FrameErrorCode;
+        message: string;
+    };
+});
+/** 主题切换，或跟随系统时深浅变了 */
+export type FrameThemeChange = {
+    type: 'theme';
+} & FrameTheme;
+/**
+ * 数据变了，重取：带 source 时只重取这个数据源。插件调了 invalidate 时推，带会话的只推给挂在那个会话上的框架；
+ * 会话或管理连接断线重连后，给每个框架推一次不带 source 的，意思是全部重取（含会话列表）
+ */
+export interface FrameInvalidate {
+    type: 'invalidate';
+    source?: string;
+}
+/** 会话列表的增量（申请了 sessions:read 的框架挂载起就收）：转发会话协议的 sessions/changed，不带 groups */
+export type FrameSessionsChanged = {
+    type: 'sessions.changed';
+} & Omit<SessionNotificationParams<'sessions/changed'>, 'groups'>;
+/** 宿主经端口发给框架的消息 */
+export type FrameHostMessage = FrameInit | FrameResult | FrameThemeChange | FrameInvalidate | FrameSessionsChanged;
+/** connect() 给出的连接。请求失败时抛出 Error，带 code（FrameErrorCode） */
+export interface FrameClient {
+    /** 会话面板挂在哪个会话上；插件页面没有 */
+    readonly sessionId?: string;
+    /** 取这一页一个数据源的数据 */
+    data(source: string, input?: Record<string, unknown>): Promise<unknown>;
+    /** 调这一页的一个动作，回处理函数给的一句话或 null；destructive 的由宿主先弹确认框，取消时抛 cancelled */
+    action(name: string, input?: Record<string, unknown>): Promise<string | null>;
+    /** 请宿主打开外站地址（经宿主的对话框）或应用内的会话 */
+    open(target: FrameOpenRequest['target']): Promise<void>;
+    /** 数据变了：带 source 时只重取这个数据源，不带时全部重取。回退订 */
+    onInvalidate(listener: (source?: string) => void): () => void;
+    /** 列会话（要 sessions:read） */
+    listSessions(params?: Omit<FrameSessionsListRequest, 'type' | 'id'>): Promise<Omit<SessionMethodResult<'sessions/list'>, 'groups'>>;
+    /** 会话列表的增量（要 sessions:read）。回退订 */
+    onSessionsChanged(listener: (change: Omit<FrameSessionsChanged, 'type'>) => void): () => void;
+    /** 停止一个会话的回合（要 turn:abort） */
+    abortTurn(params: Omit<FrameTurnAbortRequest, 'type' | 'id'>): Promise<void>;
+}
+/**
+ * 能力表：每种请求与推送要哪种宿主数据能力，null 为不要。宿主转发请求前按页面的 `frame.host` 核，没申请的回 denied；
+ * 推送只发给申请了的框架
+ */
+export declare const FRAME_REQUIRED_CAPABILITY: Readonly<Record<FrameRequest['type'] | FrameSessionsChanged['type'], FrameHostCapability | null>>;
+/** 校验的结果：不过时给出原因；消息里认得出请求 id 时一并给出，宿主据它回 invalid */
+export type FrameParseResult<T> = {
+    ok: true;
+    message: T;
+} | {
+    ok: false;
+    id?: number;
+    problem: string;
+};
+/** 校验框架发来的握手（窗口消息）。来源窗口、nonce 与主版本由宿主另核；不过的窗口消息一律忽略 */
+export declare const parseFrameHello: (value: unknown) => FrameParseResult<FrameHello>;
+/** 校验框架经端口发来的消息：类型标记、字段类型、多余的键与字符串长度；不过的请求回 invalid，不往下走 */
+export declare const parseFrameMessage: (value: unknown) => FrameParseResult<FrameMessage>;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}

package/dist/frame.js

@@ -0,0 +1,121 @@
+// ----- 插件前端 -----
+//
+// 页面默认声明式；声明式表达不了时，插件可以自带一份静态网页（插件前端），只放在插件页面与会话面板两个位置。
+// webui-server 托管它的文件，宿主把它画进 iframe，与宿主页面不同源：拿不到登录状态；可以联网，脚本只认插件自己打包的文件。
+// 要宿主的数据与动作只有一条路：经消息通道请宿主代办，调这一页声明过的数据源与动作，或用申请过的宿主数据能力。
+//
+// 本文件是这条通道的公开契约：协议版本、沙箱值、宿主数据能力的词表与能力表、消息类型与消息的校验函数。
+// 校验函数是不碰 DOM 的纯函数，宿主前端与第三方宿主前端共用，换前端时规则不漂；在途与频率上限、确认框与外链对话框
+// 涉及界面与计时，由各宿主前端照文档实现。第一版标 experimental：只做加法，加字段、加消息升次版本。
+//
+// 托管（webui-server，不要登录）：
+// GET /frames/:token/<路径>    插件包 webui/ 里的文件；token 是页面登记时随机生成的，页面撤回或重新登记后旧的回 404
+// GET /frames/_base/<路径>     宿主给框架的公用文件：助手 frame.js 与样式基线 frame.css，随本包发布
+/** 消息通道的协议版本 `<主>.<次>`：握手时主版本不同，宿主卸载框架 */
+export const FRAME_PROTOCOL_VERSION = '1.0';
+/**
+ * 框架的沙箱值：宿主 iframe 的 sandbox 属性与框架文件响应头 CSP 的 sandbox 指令同一份。只给脚本，
+ * 不给 allow-same-origin（与 allow-scripts 同给时框架能自己摘掉沙箱），也不给表单、弹窗、原生对话框、顶层跳转与下载
+ */
+export const FRAME_SANDBOX = 'allow-scripts';
+/**
+ * 宿主数据能力的词表，封闭集合，按加法扩：
+ * - `sessions:read`：读会话树与状态（请求 `sessions.list`，挂载起收到 `sessions.changed`）；
+ * - `turn:abort`：停止会话的回合（请求 `turn.abort`）。
+ * 申请了的框架与 owner 自己的界面看得一样多，不按会话收窄
+ */
+export const FRAME_HOST_CAPABILITIES = ['sessions:read', 'turn:abort'];
+/** 名字（数据源名、动作名）最多这么多个字符 */
+export const FRAME_NAME_MAX_LENGTH = 128;
+/** 标识（会话 id、回合 id、翻页游标、握手的随机数）最多这么多个字符 */
+export const FRAME_ID_MAX_LENGTH = 256;
+/** 地址最多这么多个字符 */
+export const FRAME_URL_MAX_LENGTH = 2048;
+/**
+ * 能力表：每种请求与推送要哪种宿主数据能力，null 为不要。宿主转发请求前按页面的 `frame.host` 核，没申请的回 denied；
+ * 推送只发给申请了的框架
+ */
+export const FRAME_REQUIRED_CAPABILITY = {
+    data: null,
+    action: null,
+    open: null,
+    'sessions.list': 'sessions:read',
+    'turn.abort': 'turn:abort',
+    'sessions.changed': 'sessions:read',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (max) => value => typeof value === 'string' && value !== '' && value.length <= max ? undefined : `要是 1 到 ${max} 个字符的字符串`;
+const name = text(FRAME_NAME_MAX_LENGTH);
+const ident = text(FRAME_ID_MAX_LENGTH);
+const integer = value => (Number.isSafeInteger(value) ? undefined : '要是整数');
+const flag = value => (typeof value === 'boolean' ? undefined : '要是布尔值');
+const object = value => (isRecord(value) ? undefined : '要是对象');
+const version = value => typeof value === 'string' && /^\d{1,4}\.\d{1,4}$/.test(value) ? undefined : '要是「主.次」形式的版本';
+/** 外站地址：http 或 https 的绝对地址。与宿主同源的由宿主按自己的来源再拒 */
+function webUrl(value) {
+    const problem = text(FRAME_URL_MAX_LENGTH)(value);
+    if (problem)
+        return problem;
+    try {
+        const { protocol } = new URL(value);
+        return protocol === 'http:' || protocol === 'https:' ? undefined : '只许 http、https 地址';
+    }
+    catch {
+        return '不是绝对地址';
+    }
+}
+const target = value => {
+    if (!isRecord(value) || Object.keys(value).length !== 1)
+        return '要是 { url } 或 { session }';
+    if ('url' in value)
+        return webUrl(value.url);
+    if ('session' in value)
+        return ident(value.session);
+    return '要是 { url } 或 { session }';
+};
+const HELLO_FIELDS = {
+    hello: { protocol: [version, true], nonce: [ident, true] },
+};
+const MESSAGE_FIELDS = {
+    data: { id: [integer, true], source: [name, true], input: [object, false] },
+    action: { id: [integer, true], action: [name, true], input: [object, false] },
+    open: { id: [integer, true], target: [target, true] },
+    'sessions.list': {
+        id: [integer, true],
+        parentId: [ident, false],
+        archived: [flag, false],
+        cursor: [ident, false],
+        limit: [integer, false],
+    },
+    'turn.abort': { id: [integer, true], sessionId: [ident, true], turnId: [ident, false] },
+    leaving: {},
+};
+function parse(value, table) {
+    if (!isRecord(value))
+        return { ok: false, problem: '消息要是对象' };
+    const id = Number.isSafeInteger(value.id) ? value.id : undefined;
+    const fail = (problem) => ({ ok: false, ...(id === undefined ? {} : { id }), problem });
+    const fields = typeof value.type === 'string' && Object.hasOwn(table, value.type) ? table[value.type] : undefined;
+    if (!fields)
+        return fail(`不认识的消息 ${String(value.type)}`);
+    for (const key of Object.keys(value)) {
+        if (key !== 'type' && !Object.hasOwn(fields, key))
+            return fail(`多余的键：${key}`);
+    }
+    for (const [key, [rule, required]] of Object.entries(fields)) {
+        if (value[key] === undefined) {
+            if (required)
+                return fail(`缺少 ${key}`);
+            continue;
+        }
+        const problem = rule(value[key]);
+        if (problem)
+            return fail(`${key} ${problem}`);
+    }
+    return { ok: true, message: value };
+}
+/** 校验框架发来的握手（窗口消息）。来源窗口、nonce 与主版本由宿主另核；不过的窗口消息一律忽略 */
+export const parseFrameHello = (value) => parse(value, HELLO_FIELDS);
+/** 校验框架经端口发来的消息：类型标记、字段类型、多余的键与字符串长度；不过的请求回 invalid，不往下走 */
+export const parseFrameMessage = (value) => parse(value, MESSAGE_FIELDS);
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}