Skip to content

Commit 271df4a

Browse files
SisyphusZhengSisyphusZheng
committed
@
fix(ci): JSR publish excluded-module + deno fmt - hub/deno.json: add "mod.ts" to publish.include (was producing error[excluded-module] because mod.ts was not in the file list) - less-showcase-panel.ts: deno-fmt-ignore-file for Lit dynamic tag names (<${tag}>) that dprint cannot parse - deno fmt: apply formatting to ~28 files across docs/, packages/, www/ @
1 parent 4c814bf commit 271df4a

35 files changed

Lines changed: 4696 additions & 559 deletions

‎README.md‎

Lines changed: 96 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,34 @@
22

33
[English](./README.en.md) | 简体中文
44

5-
**全栈框架 + 通用 WC 渲染引擎 + Registry Hub** — 以 Web Components 为一等公民的全栈开发平台。基于 Declarative Shadow DOM 的零 JS 首屏渲染，Island 架构按需升级交互，Hono + Serverless API 提供后端能力，Registry Hub 一键发现和安装 WC 组件。
5+
**Web Components 全栈框架** — 以 Declarative Shadow DOM 为一等渲染原语，将 Web 标准作为框架本身。海洋（DSD 组件）SSR 直出、零框架开销；岛屿（Pure Island）按需接入 Lit / Preact / FAST / React，借用框架的 reactivity。
66

77
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
88
[![Deno](https://img.shields.io/badge/Deno-2.7%2B-000000)](https://deno.com/)
99
[![JSR](https://img.shields.io/badge/JSR-published-blue)](https://jsr.io/@lessjs/core)
10-
[![@lessjs/core](https://img.shields.io/jsr/v/@lessjs/core?label=@lessjs/core)](https://jsr.io/@lessjs/core)
10+
[![@lessjs/core](https://img.shields.io/badge/jsr-v0.19.0-blue?label=@lessjs/core)](https://jsr.io/@lessjs/core)
11+
12+
## 海洋-岛屿架构
13+
14+
```
15+
┌──────────────────────────────────────────┐
16+
│ 海洋（~80%） │
17+
│ DSD 组件 → SSR 渲染 Shadow DOM │
18+
│ → 浏览器原生解析，零 JS 可见 │
19+
│ → DsdElement 水合：只绑事件，不动 DOM │
20+
│ → 框架无关，纯原生 HTMLElement │
21+
│ │
22+
│ ┌──────────────────────────────────┐ │
23+
│ │ 岛屿（~20%） │ │
24+
│ │ Pure Island → 客户端渲染 │ │
25+
│ │ → 需要 reactivity │ │
26+
│ │ → 按需选框架: Lit/FAST/Preact │ │
27+
│ │ → 策略: eager/lazy/visible/idle │ │
28+
│ └──────────────────────────────────┘ │
29+
└──────────────────────────────────────────┘
30+
```
31+
32+
**核心理念**：海洋不需要 reactivity（DOM 已在 SSR 中渲染完毕），岛屿才需要。别的框架海洋是"裸 HTML"，LessJS 的海洋是"封装好的 Web Components"。
1133

1234
## 三支柱架构
1335

@@ -21,8 +43,9 @@ LessJS
2143
│ └── Serverless 部署（CF Pages / Deno Deploy）
2244
│
2345
├── 2. 通用 WC 渲染引擎
24-
│ ├── DSD 字符串渲染（renderDSD — 纯字符串拼接）
25-
│ ├── 多框架适配器（Lit / React / Vanilla → Vue）
46+
│ ├── DSD 字符串渲染（renderDSD — 浏览器原生解析）
47+
│ ├── DsdElement 基类 — 零框架依赖的 DSD 组件
48+
│ ├── 多框架适配器 — 仅服务 Pure Island SSR
2649
│ ├── 渲染时机无关（build-time / ISR / request-time）
2750
│ └── 兼容性分类 + 验证
2851
│
@@ -34,6 +57,38 @@ LessJS
3457

3558
**不是 SSG 框架** — SSG 只是渲染引擎的当前使用模式。`renderDSD()` **架构上**是渲染时机无关的：build-time (SSG)、cache-expiry-time (ISR)、request-time (SSR) 用的是同一套引擎。**当前实现**: SSG only, ISR/SSR 计划中。
3659

60+
## 渲染管线
61+
62+
```
63+
海洋（DSD 组件）:
64+
render(): string → renderDSD() → <template shadowrootmode="open">
65+
↓
66+
浏览器原生解析 Shadow DOM
67+
↓
68+
DsdElement.hydrateEvents()
69+
↓
70+
可交互 ✅（零框架开销）
71+
72+
岛屿（Pure Island）:
73+
框架 render() → Adapter → renderDSD() → 空壳 custom element
74+
↓
75+
客户端框架接管 (Lit/FAST/Preact...)
76+
↓
77+
岛屿可交互 ✅
78+
```
79+
80+
**关键差异**：海洋的 `render()` 直接返回 string，不需要任何框架模板引擎。事件绑定通过声明式 `hydrateEvents` 完成，DOM 无需重建。
81+
82+
## 原生 CSS 栈
83+
84+
```
85+
Open Props — 设计 token（间距/颜色/阴影/动效），零维护成本
86+
CSSStyleSheet — 组件样式（adoptedStyleSheets，一次解析全局共享）
87+
CSS Parts ::part() — 组件外部定制 API
88+
```
89+
90+
三层极简栈，纯 W3C 标准，与 Shadow DOM + DSD 天然配合。
91+
3792
## 特性
3893

3994
### 支柱 1：全栈框架
@@ -47,8 +102,9 @@ LessJS
47102

48103
### 支柱 2：通用 WC 渲染引擎
49104

50-
- **Declarative Shadow DOM** — WHATWG 标准，零 JS 首屏
51-
- **Island 升级** — 仅交互组件加载客户端 JS（`client:load/idle/visible/only` — 计划中）
105+
- **Declarative Shadow DOM** — WHATWG 标准，零 JS 首屏可见
106+
- **DsdElement 基类** — 原生 HTMLElement，零框架依赖，声明式事件绑定
107+
- **Island 升级** — 仅交互组件加载客户端 JS（`eager/lazy/idle/visible`）
52108
- **多适配器** — Lit / React / Vanilla 适配器，同一页面多框架共存
53109
- **Universal WC Engine** — 自动检测第三方 Web Component，4 级兼容性分类
54110
- **Renderer Protocol** — 结构化渲染输出 + 错误分类 + DSD 指标
@@ -79,33 +135,25 @@ deno task build # SSG 构建
79135

80136
## 包
81137

82-
| 包 | 职责 |
83-
| ------------------------- | ---------------------------------------------------------------------- |
84-
| `@lessjs/core` | DSD 渲染器、Renderer Protocol、CEM 解析器、兼容性分类器、manifest 验证 |
85-
| `@lessjs/adapter-vite` | Vite 编排、路由扫描、SSG 管线、CEM 自动检测 |
86-
| `@lessjs/adapter-lit` | Lit TemplateResult → DSD HTML |
87-
| `@lessjs/adapter-react` | React 适配器 |
88-
| `@lessjs/adapter-vanilla` | Vanilla JS 适配器 |
89-
| `@lessjs/app` | 统一入口 `lessjs()` |
90-
| `@lessjs/content` | Blog、Nav、Sitemap 插件 |
91-
| `@lessjs/i18n` | 国际化路由 |
92-
| `@lessjs/ui` | Web Components 组件库 |
93-
| `@lessjs/signals` | Signals 辅助 |
94-
| `@lessjs/rpc` | Fetch RPC |
95-
| `@lessjs/hub` | Registry Hub — schema、indexer、scanner、snapshot-renderer |
96-
| `@lessjs/create` | 项目脚手架 CLI |
97-
98-
## 渲染管线
99-
100-
```
101-
render() → RenderAdapter → renderDSD() → DSD HTML → 浏览器解析
102-
↓
103-
customElements.upgrade()
104-
↓
105-
dsd-interactive → 绑定 hydrateEvents
106-
```
107-
108-
**渲染时机无关**：同一套 `renderDSD()` 引擎在不同时机调用：
138+
| 包 | 职责 |
139+
| ------------------------- | ------------------------------------------------------------------------- |
140+
| `@lessjs/core` | DSD 渲染器、DsdElement 基类、Renderer Protocol、CEM 解析器、manifest 验证 |
141+
| `@lessjs/adapter-vite` | Vite 编排、路由扫描、SSG 管线、CEM 自动检测 |
142+
| `@lessjs/adapter-lit` | Lit 适配器（Pure Island SSR） |
143+
| `@lessjs/adapter-react` | React 适配器（Pure Island SSR） |
144+
| `@lessjs/adapter-vanilla` | Vanilla JS 适配器 |
145+
| `@lessjs/app` | 统一入口 `lessjs()` |
146+
| `@lessjs/content` | Blog、Nav、Sitemap 插件 |
147+
| `@lessjs/i18n` | 国际化路由 |
148+
| `@lessjs/ui` | Web Components 组件库（原生 DSD 组件，目标零 Lit 依赖） |
149+
| `@lessjs/signals` | Signals 辅助 |
150+
| `@lessjs/rpc` | Fetch RPC |
151+
| `@lessjs/hub` | Registry Hub — schema、indexer、scanner、snapshot-renderer |
152+
| `@lessjs/create` | 项目脚手架 CLI |
153+
154+
## 渲染时机无关
155+
156+
同一套 `renderDSD()` 引擎在不同时机调用：
109157

110158
| 模式 | 何时调用 renderDSD() | 数据新鲜度 | 需要服务器 |
111159
| ------------- | -------------------- | ----------------- | ------------ |
@@ -127,27 +175,29 @@ node_modules/*/custom-elements.json → CEM Parser → 4级分类器 → SSR adm
127175

128176
| 维度 | LessJS | Astro | Fresh | Next.js |
129177
| ------------ | ---------------------- | -------------- | -------------- | ------------- |
130-
| **定位** | 全栈 + WC引擎 + Hub | 全栈（多框架） | 全栈（Preact） | 全栈（React） |
178+
| **定位** | WC 全栈 + DSD 原生 | 全栈（多框架） | 全栈（Preact） | 全栈（React） |
131179
| **WC 原生** | ✅ DSD 一等公民 | ❌ 当普通元素 | ❌ Preact-only | ❌ |
132180
| **首屏 JS** | 0 KB | 0 KB | ~23 KB | ~90 KB |
133-
| **跨框架** | Lit/React/Vanilla 共存 | 多框架共存 | Preact only | React only |
181+
| **海洋组件** | ✅ Shadow DOM 封装 | ❌ 裸 HTML | ❌ 裸 HTML | ❌ 裸 HTML |
182+
| **跨框架** | 海洋零框架，岛屿自由选 | 多框架共存 | Preact only | React only |
183+
| **CSS 方案** | 纯 W3C 标准栈 | Scoped CSS | Tailwind | CSS Modules |
134184
| **Registry** | ✅ Hub 内建 | ❌ | ❌ | ❌ |
135185
| **后端** | Hono + Serverless | 内置 | Oak | 内置 |
136186

137-
**核心差异化**：LessJS 以 DSD 和 Web Components 作为首要渲染契约，而非在框架特定组件模型之上叠加优化。
187+
**核心差异化**：LessJS 是唯一把 Shadow DOM 封装带到服务端的框架——海洋即组件，而其他框架的静态 HTML 仅仅是 HTML。
138188

139189
## 路线图
140190

141-
| 版本 | 目标 | 状态 |
142-
| ----- | ------------------------------------ | --------- |
143-
| v0.15 | Renderer Kernel Protocol | ✅ 完成 |
144-
| v0.16 | WC Package Protocol | ✅ 完成 |
145-
| v0.17 | Ecosystem Entry + SSR 边界 | ✅ 完成 |
146-
| v0.18 | Universal WC Engine | ✅ 完成 |
147-
| v0.19 | **Registry Hub + Component Browser** | **当前** |
148-
| v0.20 | Islands 策略 + 全栈地基 | 📋 计划中 |
149-
| v0.21 | 全栈框架成型（ISR + Vue + Supabase） | 📋 计划中 |
150-
| v1.0 | API Freeze | 🚀 远期 |
191+
| 版本 | 目标 | 状态 |
192+
| ----- | ----------------------------------------------- | --------- |
193+
| v0.15 | Renderer Kernel Protocol | ✅ 完成 |
194+
| v0.16 | WC Package Protocol | ✅ 完成 |
195+
| v0.17 | Ecosystem Entry + SSR 边界 | ✅ 完成 |
196+
| v0.18 | Universal WC Engine | ✅ 完成 |
197+
| v0.19 | **Registry Hub + Component Browser** | **当前** |
198+
| v0.20 | DsdElement 原生基类 + Islands 策略 + CSS 原生栈 | 📋 计划中 |
199+
| v0.21 | 全栈框架成型（ISR + SSR + Supabase） | 📋 计划中 |
200+
| v1.0 | API Freeze | 🚀 远期 |
151201

152202
详见 [ADR 文档](docs/adr/) 和 [官方文档](https://lessjs.org)。
153203

0 commit comments

Comments
 (0)