# Astro、Next 与辅助工具参考

客户端和服务器集成入口，以及导出的辅助函数。

<span id="elegir-una-entrada-del-paquete"></span>

<span class="section-anchor" id="section-1"></span>

## 选择软件包入口

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。[服务器示例](/zh-cn/docs/framework/server-recipes/)展示如何组合 SSR 模块。使用辅助函数时，请从 `wu-framework` 显式导入指定名称。

<span class="section-anchor" id="section-2"></span>

## wuIntegration

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

`wuIntegration(options?): AstroIntegration`

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

```js
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`.

<span class="section-anchor" id="section-3"></span>

## Astro WuShell

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

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

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

```astro
---
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`.

<span class="section-anchor" id="section-4"></span>

## Astro WuApp

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

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

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

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

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

参考：`integrations/astro/WuApp.astro`.

<span class="section-anchor" id="section-5"></span>

## 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 实例，移除宿主时卸载应用。

```astro
---
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`.

<span class="section-anchor" id="section-6"></span>

## Next WuShell

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

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

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

```jsx
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`.

<span class="section-anchor" id="section-7"></span>

## Next WuApp

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

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

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

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

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

参考：`integrations/next/WuApp.js`.

<span class="section-anchor" id="section-8"></span>

## 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 实例，移除宿主时卸载应用。

```jsx
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`.

<span class="section-anchor" id="section-9"></span>

## Next WuMount

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

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

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

```jsx
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`.

<span class="section-anchor" id="section-10"></span>

## parseVersion

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

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

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

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

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

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

<span class="section-anchor" id="section-11"></span>

## compareVersions

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

`compareVersions(a, b): number`

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

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

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

<span class="section-anchor" id="section-12"></span>

## satisfies

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

`satisfies(version, range): boolean`

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

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

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

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

<span class="section-anchor" id="section-13"></span>

## silenceAllLogs

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

`silenceAllLogs(): void`

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

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

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

参考：`src/index.js`.

<span class="section-anchor" id="section-14"></span>

## enableAllLogs

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

`enableAllLogs(): void`

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

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

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

参考：`src/index.js`.