简体中文 | English
DSD-first Web Components 应用框架 - LessJS 把标准优先的 DSD 渲染引擎、渐进式 Island、Hono API Route 和早期 Registry Hub 组合在一起，让 Web Components 成为一等公民。
┌──────────────────────────────────────────┐
│ 海洋（~80%） │
│ DSD 组件 → SSR 渲染 Shadow DOM │
│ → 浏览器原生解析，零 JS 可见 │
│ → DsdElement 水合：只绑事件，不动 DOM │
│ → 框架无关，纯原生 HTMLElement │
│ │
│ ┌──────────────────────────────────┐ │
│ │ 岛屿（~20%） │ │
│ │ Pure Island → 客户端渲染 │ │
│ │ → 需要 reactivity │ │
│ │ → 按需选框架: Lit/FAST/Preact │ │
│ │ → 策略: eager/lazy/visible/idle │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────────┘
核心理念：海洋不需要 reactivity（DOM 已在 SSR 中渲染完毕），岛屿才需要。别的框架海洋是"裸 HTML"，LessJS 的海洋是"封装好的 Web Components"。
项目线：v0.20.0 Ocean-Island Architecture。
当前生产渲染模式是 SSG + Declarative Shadow DOM。renderDSD() 的架构设计允许
未来在缓存过期时运行 ISR，或在请求时运行 SSR，但 ISR/SSR 仍是路线图能力，不应写成已发布保证。
包版本目前是分阶段发布状态：@lessjs/ui 已承载 v0.20.0 Ocean-Island 工作，
核心包已协调统一版本。
LessJS
|
+-- 1. 应用框架
| +-- 文件约定路由
| +-- Hono API Route
| +-- Vite dev server 与 SSG build
| +-- 面向 serverless 的部署模型
|
+-- 2. DSD/WC 渲染引擎
| +-- DsdElement, renderDSD(), StyleSheet
| +-- Declarative Shadow DOM 输出
| +-- Lit / React / Vanilla 适配器
| +-- 兼容性准入与 dsd-report.json
|
+-- 3. Registry Hub
+-- 包发现
+-- 兼容性报告与快照
+-- validation-gated less add workflow
- DSD-first 渲染 - SSR-capable 组件输出
<template shadowrootmode="open">。 - DsdElement - 零依赖
HTMLElement基类，用于 DSD-native Web Components。 - SSR-safe StyleSheet - 浏览器与 Deno/Node 构建都可用的样式表抽象。
- Ocean-Island UI 模型 - 大部分 UI 是 DSD-native ocean 组件，复杂交互保留在 island。
- Hono API Route - 基础 API route 已接入应用路由树。
- Registry evidence pipeline - Hub record、包验证、快照、
less add已形成早期基础设施。 - 发布门禁 - fmt、lint、typecheck、test、build、e2e、audit、Hub 验证和 DSD report gate。
- Hydration strategies - 用户可见的
client:load、client:idle、client:visible、client:only。 - ISR cache layer - stale-while-revalidate HTML 再生成。
- Request context - API 与未来 SSR 路径共享 env、platform、request 数据。
- Signals + DsdElement - 不把 DSD 组件变成框架 runtime 的响应式 DOM 更新。
- Hub 增长 - 更多真实 Web Component 包和更清晰的兼容性 badge。
deno run -A jsr:@lessjs/create my-app
cd my-app
deno task dev
deno task build要求：Deno 2.7+，以及支持 Declarative Shadow DOM 的现代浏览器。
| Package | 职责 |
|---|---|
@lessjs/core |
DSD renderer、DsdElement、StyleSheet、renderer protocol、CEM parser、compatibility classifier |
@lessjs/adapter-vite |
Vite 编排、路由扫描、SSG 管线、island entry 生成 |
@lessjs/adapter-lit |
Lit adapter，主要保留给 island 和兼容路径 |
@lessjs/adapter-react |
React adapter |
@lessjs/adapter-vanilla |
Vanilla Web Component adapter |
@lessjs/app |
统一入口 lessjs() |
@lessjs/content |
Blog、nav、sitemap 构建插件 |
@lessjs/i18n |
Locale 展开与路由辅助 |
@lessjs/ui |
DSD-native Web Components 与 island 示例 |
@lessjs/signals |
Signals helpers 与 island effects |
@lessjs/rpc |
Fetch-based RPC controller |
@lessjs/hub |
Registry Hub schema、indexer、scanner、validator、snapshots |
@lessjs/create |
项目脚手架 CLI |
route component
-> renderDSD()
-> <template shadowrootmode="open">
-> browser parses DSD
-> custom element upgrade
-> hydrateEvents / island runtime only where needed
| Mode | 状态 | 渲染时机 | 服务器要求 |
|---|---|---|---|
| SSG | 已发布 | build time | 构建后不需要 |
| ISR | 下一阶段 | cache expiry | edge/serverless function |
| SSR | 后续 | every request | always-on request runtime |
LessJS 不承诺任意 Web Component 都能自动 SSR。每个组件应该得到一个确定结果：
- 通过声明 adapter 或验证过的包契约进入 SSR/SSG
- 需要浏览器 API 时降级为 client-only
- metadata 无效或不安全时在生成构建产物前拒绝
| 版本 | 目标 | 状态 |
|---|---|---|
| v0.15 | Renderer Kernel Protocol | Done |
| v0.16 | WC Package Protocol | Done |
| v0.17 | Ecosystem Entry + SSR Boundary | Done |
| v0.18 | Universal WC Engine | Done |
| v0.19 | Registry Hub + Component Browser | Done |
| v0.20 | Ocean-Island Architecture + DSD-native UI | Current |
| v0.21 | Hydration Strategies + ISR + API Route parity | Next |
| v0.22 | DsdElement + Signals rendering | Planned |
| v1.0 | Stable Engine contracts | Vision |
详见 ADR docs、SOP docs 和 Roadmap。
docs/
+-- adr/ architecture decision records
+-- changelog/ version changelogs
+-- sop/ standard operating procedures
+-- status/ project status and review archive
+-- roadmap/ version planning
参见 CONTRIBUTING.md。
MIT