Astro、Next 与辅助工具参考

选择软件包入口

Astro 组件从 wu-framework/integrations/astro/*.astro 导入，astro.config factory 位于 wu-framework/integrations/astro。Next 可使用 wu-framework/integrations/next barrel，或 WuShell、WuApp、WuAppSSR 和 WuMount 子路径。

WuShell 初始化目录，WuApp 在客户端挂载，WuAppSSR 组合初始 HTML 并提供 hydration 桥接。UI 组件不构成额外远程注册；服务器、目录和浏览器入口必须保持相同应用名称。

Astro 示例使用 frontmatter，Next 示例使用 JSX。服务器示例展示如何组合 SSR 模块。使用辅助函数时，请从 wu-framework 显式导入指定名称。

wuIntegration

从 astro.config 配置 Vite 并注入客户端初始化。

wuIntegration(options?): AstroIntegration

• 参数： apps、sandbox、cdn 和 debug。
• 返回值： 含 astro:config:setup hook 的 Astro 集成对象。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

import { defineConfig } from 'astro/config';
import wuIntegration from 'wu-framework/integrations/astro';
export default defineConfig({ integrations: [wuIntegration({ apps: [{ name: 'card', url: '/apps/card' }], sandbox: 'module' })] });

cdn 向 head 添加 UMD script，但 apps 自动初始化仍导入 wu-framework 软件包。此处选择 CDN 不会自动替代该导入。

参考：integrations/astro/index.js.

Astro WuShell

输出目录配置，并在客户端 script 中执行 wu.init。

<WuShell apps={apps} sandbox? debug?>children</WuShell>

• 参数： apps 必填；sandbox 和 debug。渲染自身 slot。
• 返回值： 带 JSON 配置和打包 script 的 Astro markup。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

---
import WuShell from 'wu-framework/integrations/astro/WuShell.astro';
---
<WuShell apps={[{ name: 'card', url: '/apps/card' }]}><main>Contenido</main></WuShell>

不是响应式 provider；修改 HTML 属性不会更新运行时配置，也不会创建第二个实例。

参考：integrations/astro/WuShell.astro.

Astro WuApp

为已注册应用输出客户端挂载点。

<WuApp name="card" lazy? class? style? />

• 参数： name；lazy 启用 IntersectionObserver；容器 class 和 style。
• 返回值： Astro 容器和挂载 script。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

---
import WuApp from 'wu-framework/integrations/astro/WuApp.astro';
---
<WuApp name="card" lazy />

从 shell 或集成初始化并注册应用。组件不接收 module，也不渲染 SSR。

参考：integrations/astro/WuApp.astro.

Astro WuAppSSR

在 Astro SSR 或 SSG 中渲染应用，并发布 props 供可选 hydration。

<WuAppSSR name module props? styles? hydrate? fallbackToClient? />

• 参数： 服务器 module 必填；hydrate 和 fallbackToClient 为 true；class/style 可选。
• 返回值： 带 SSR 标记的初始 HTML，启用 hydration 时包含 JSON 状态。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

---
import WuAppSSR from 'wu-framework/integrations/astro/WuAppSSR.astro';
import { renderHtml } from 'wu-framework/server';
const module = renderHtml(() => '<p>Resumen</p>');
---
<WuAppSSR name="card" module={module} hydrate={false} />

hydrate:false 只保留服务器 HTML。fallbackToClient:false 传播 SSR 错误。组件不暴露 renderApp 全部 nonce/shadowMode 选项。

参考：integrations/astro/WuAppSSR.astro.

Next WuShell

在客户端初始化运行时，通过 shell Promise 协调后代。

WuShell({apps, sandbox?, debug?, children?}): ReactNode

• 参数： apps 和 children；sandbox/debug。
• 返回值： children，不增加 DOM wrapper。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

import { WuShell } from 'wu-framework/integrations/next';
export default function Layout({ children }) {
  return <WuShell apps={[{ name: 'card', url: '/apps/card' }]}>{children}</WuShell>;
}

每次 shell 挂载初始化一次；之后修改 apps 不会自动重新配置目录。

参考：integrations/next/WuShell.js.

Next WuApp

从 Next 客户端组件挂载 WU 应用。

WuApp({name, appName?, lazy?, ...props}): ReactNode

• 参数： 注册名称、lazy、className/style、onMount/onUnmount 和额外 props。
• 返回值： React 管理的宿主元素。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

import { WuApp } from 'wu-framework/integrations/next';
export default function Page() { return <WuApp name="card" lazy />; }

导入集成子路径，不要导入 runtime 的 WuApp；后者是另一种命令式 wrapper。

参考：integrations/next/WuApp.js.

Next WuAppSSR

渲染服务器模块，hydrate 为 true 时添加客户端桥接。

WuAppSSR({name, module, props?, ...options}): Promise<ReactNode>

• 参数： module 必填；props、styles、shadowMode、hydrate true、fallbackToClient true。
• 返回值： 包含 SSR HTML 和可选 WuMount 桥接的 React 树。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： 每个文档保持一个 shell 实例，移除宿主时卸载应用。

import { WuAppSSR } from 'wu-framework/integrations/next';
import { renderHtml } from 'wu-framework/server';
const module = renderHtml(() => '<p>Resumen</p>');
export default async function Page() {
  return <WuAppSSR name="card" module={module} hydrate={false} />;
}

浏览器 bundle 必须注册兼容 hydrate 才能接管 DOM；服务器 renderer 不会自动提供该生命周期。

参考：integrations/next/WuAppSSR.js.

Next WuMount

将已有服务器容器连接到 core 的挂载或 hydration。

WuMount({name, containerId, props?, ssr?}): null

• 参数： name、已有元素 id、可选 props 和 ssr true。
• 返回值： null；只执行客户端副作用。
• 错误： 处理注册或模块加载失败；组件可能按其约定在控制台记录错误。
• 权限： 宿主控制 WU 目录和策略；集成本身不向应用授予能力。
• 清理： effect 移除时卸载，也会撤销取消后才完成的 mount。不销毁 singleton。

import WuMount from 'wu-framework/integrations/next/WuMount';
const bridge = <WuMount name="card" containerId="wu-app-card" props={{ count: 1 }} />;

props 在挂载前发布，但不属于 effect 依赖，因此修改它不构成响应式 update 通道。

参考：integrations/next/WuMount.js.

parseVersion

拆分版本，供版本化契约使用。

parseVersion(version): [number, number, number]

• 参数： 值转换为字符串；移除 v/= 前缀、prerelease 和 build。非数值部分转换为 0。
• 返回值： 元组 [major,minor,patch]。
• 错误： 不是严格验证器；非数值版本可能得到 [0,0,0]。
• 权限： 辅助函数，没有 grants 或自身特权访问。
• 清理： 不创建持久资源。

import { parseVersion } from 'wu-framework';
console.log(parseVersion('1.2.3'));

与 contracts 使用相同语义，不能替代 node-semver 全部规则。

参考：src/core/wu-semver.js.

compareVersions

比较版本结构，确定兼容性顺序。

compareVersions(a, b): number

• 参数： 两个版本字符串或 [major,minor,patch] 元组。
• 返回值： 负值、零或正值。
• 错误： 按自身实现验证，不等同于通用软件包解析器。
• 权限： 辅助函数，没有 grants 或自身特权访问。
• 清理： 不创建持久资源。

import { compareVersions, parseVersion } from 'wu-framework';
console.log(compareVersions(parseVersion('1.0.0'), parseVersion('2.0.0')));

参考：src/core/wu-semver.js.

satisfies

检查 WU 契约支持的版本范围。

satisfies(version, range): boolean

• 参数： 版本和范围字符串。
• 返回值： Boolean。
• 错误： 按自身实现验证，不等同于通用软件包解析器。
• 权限： 辅助函数，没有 grants 或自身特权访问。
• 清理： 不创建持久资源。

import { satisfies } from 'wu-framework';
console.log(satisfies('1.2.3', '^1.0.0'));

支持的运算符以 WU 实现为准，不要假定支持完整 npm 语法。

参考：src/core/wu-semver.js.

silenceAllLogs

禁用框架中央 logger 的日志级别。

silenceAllLogs(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 按自身实现验证，不等同于通用软件包解析器。
• 权限： 辅助函数，没有 grants 或自身特权访问。
• 清理： 不创建持久资源。

import { silenceAllLogs } from 'wu-framework';
silenceAllLogs();

不会拦截浏览器全部 console，也不保证静默适配器或应用 console。

参考：src/index.js.

enableAllLogs

启用框架中央 logger 的日志级别。

enableAllLogs(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 按自身实现验证，不等同于通用软件包解析器。
• 权限： 辅助函数，没有 grants 或自身特权访问。
• 清理： 不创建持久资源。

import { enableAllLogs } from 'wu-framework';
enableAllLogs();

控制该已导入模块共享的中央 logger。

参考：src/index.js.