Skip to content

Commit bba0ab5

Browse files
SisyphusZhengSisyphusZheng
committed
Merge branch 'dev'
2 parents 59b3022 + 219bed9 commit bba0ab5

23 files changed

Lines changed: 1913 additions & 303 deletions

File tree

‎README.en.md‎

Lines changed: 42 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,11 @@ interactive components that need browser APIs.
1616
- **SSG-first** — static HTML output, zero-JS first paint
1717
- **Declarative Shadow DOM** — WHATWG standard, no framework markers
1818
- **Island upgrade** — client JS loaded only for interactive components
19+
- **Universal WC Engine** (v0.18.0) — auto-detect third-party WC packages, 4-tier compatibility (ssr-capable / client-only / rejected / experimental-dom)
20+
- **validate-manifest CLI** (v0.18.1) — validate CEM manifests before install
21+
- **less add safe install** (v0.18.2) — dry-run + validation gate + plan generation
1922
- **Renderer Protocol** — structured render output, error taxonomy, DSD metrics
20-
- **Multi-adapter** — Lit built-in, extensible to non-Lit adapters
23+
- **Multi-adapter** — Lit / React / Vanilla adapters
2124
- **Deno workspace** — pure ESM, no `package.json`
2225

2326
## Quick Start
@@ -33,18 +36,20 @@ Requirements: Deno 2.7+ / modern browser with Declarative Shadow DOM support
3336

3437
## Packages
3538

36-
| Package | Role |
37-
| ---------------------- | ---------------------------------------------------- |
38-
| `@lessjs/core` | DSD renderer, Renderer Protocol, islands, navigation |
39-
| `@lessjs/adapter-vite` | Vite orchestration, route scanning, SSG pipeline |
40-
| `@lessjs/adapter-lit` | Lit TemplateResult → DSD HTML bridge |
41-
| `@lessjs/app` | Unified `lessjs()` entry |
42-
| `@lessjs/content` | Blog, nav, sitemap build plugins |
43-
| `@lessjs/i18n` | Locale expansion and route helpers |
44-
| `@lessjs/ui` | Web Components library and package islands |
45-
| `@lessjs/signals` | Signals helpers and island effects |
46-
| `@lessjs/rpc` | Fetch-based RPC controller |
47-
| `@lessjs/create` | Project scaffold CLI |
39+
| Package | Role |
40+
| ------------------------- | ------------------------------------------------------------------------------------------ |
41+
| `@lessjs/core` | DSD renderer, Renderer Protocol, CEM parser, compatibility classifier, manifest validation |
42+
| `@lessjs/adapter-vite` | Vite orchestration, route scanning, SSG pipeline, CEM auto-detection |
43+
| `@lessjs/adapter-lit` | Lit TemplateResult → DSD HTML bridge |
44+
| `@lessjs/adapter-react` | React adapter |
45+
| `@lessjs/adapter-vanilla` | Vanilla JS adapter |
46+
| `@lessjs/app` | Unified `lessjs()` entry |
47+
| `@lessjs/content` | Blog, nav, sitemap build plugins |
48+
| `@lessjs/i18n` | Locale expansion and route helpers |
49+
| `@lessjs/ui` | Web Components library and package islands |
50+
| `@lessjs/signals` | Signals helpers and island effects |
51+
| `@lessjs/rpc` | Fetch-based RPC controller |
52+
| `@lessjs/create` | Project scaffold CLI |
4853

4954
## Rendering Pipeline
5055

@@ -56,16 +61,32 @@ render() → RenderAdapter → renderDSD() → DSD HTML → SSG → browser pars
5661
dsd-interactive → bind hydrateEvents
5762
```
5863

59-
## Roadmap
64+
## Third-Party Compatibility Pipeline (v0.18.x)
6065

61-
| Version | Target | Status |
62-
| ------- | ------------------------ | -------------- |
63-
| v0.15 | Renderer Kernel Protocol | In development |
64-
| v0.16 | WC Package Protocol | Planned |
65-
| v0.17 | Ecosystem Entry | Planned |
66-
| v1.0 | API Freeze | Future |
66+
```
67+
node_modules/*/custom-elements.json → CEM Parser → 4-tier classifier → SSR admission
68+
↓
69+
less validate-manifest (CLI)
70+
↓
71+
less add (safe install)
72+
```
73+
74+
## Roadmap
6775

68-
See [ADR-0024](docs/adr/README.md) and [ADR-0025](docs/adr/0025-renderer-protocol.md).
76+
| Version | Target | Status |
77+
| ------- | ----------------------------------- | ----------- |
78+
| v0.15 | Renderer Kernel Protocol | ✅ Done |
79+
| v0.16 | WC Package Protocol | ✅ Done |
80+
| v0.17 | Ecosystem Entry + SSR Boundary | ✅ Done |
81+
| v0.18 | **Universal WC Engine** | **Current** |
82+
| v0.18.0 | CEM parser + 4-tier + auto-detect | ✅ Done |
83+
| v0.18.1 | validate-manifest CLI | ✅ Done |
84+
| v0.18.2 | less add safe install flow | ✅ Done |
85+
| v0.18.3 | DOM simulation experiment (planned) | 📋 Planned |
86+
| v0.19 | Registry Hub + Platform | 📋 Planned |
87+
| v1.0 | API Freeze | 🚀 Far term |
88+
89+
See [ADR docs](docs/adr/) and [lessjs.org](https://lessjs.org) for details.
6990

7091
## Governance Docs
7192

‎README.md‎

Lines changed: 42 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,11 @@ Deno-first Web Components 框架。基于 **Declarative Shadow DOM SSR/SSG + Isl
1414
- **SSG-first** — 静态 HTML 输出，零 JS 首屏
1515
- **Declarative Shadow DOM** — WHATWG 标准，无框架标记
1616
- **Island 升级** — 仅交互组件加载客户端 JS
17+
- **Universal WC Engine** (v0.18.0) — 自动检测第三方 Web Component，4 级兼容性分类（ssr-capable / client-only / rejected / experimental-dom）
18+
- **validate-manifest CLI** (v0.18.1) — 安装前验证 CEM manifest 兼容性
19+
- **less add 安全安装** (v0.18.2) — dry-run + 验证门禁 + 计划生成
1720
- **Renderer Protocol** — 结构化渲染输出 + 错误分类 + DSD 指标
18-
- **多适配器** — Lit 内置，可扩展非 Lit 适配器
21+
- **多适配器** — Lit / React / Vanilla 适配器
1922
- **Deno workspace** — 纯 ESM，零 `package.json`
2023

2124
## 快速开始
@@ -31,18 +34,20 @@ deno task build # SSG 构建
3134

3235
## 包
3336

34-
| 包 | 职责 |
35-
| ---------------------- | ------------------------------------------------- |
36-
| `@lessjs/core` | DSD 渲染器、Renderer Protocol、island、navigation |
37-
| `@lessjs/adapter-vite` | Vite 编排、路由扫描、SSG 管线 |
38-
| `@lessjs/adapter-lit` | Lit TemplateResult → DSD HTML |
39-
| `@lessjs/app` | 统一入口 `lessjs()` |
40-
| `@lessjs/content` | Blog、Nav、Sitemap 插件 |
41-
| `@lessjs/i18n` | 国际化路由 |
42-
| `@lessjs/ui` | Web Components 组件库 |
43-
| `@lessjs/signals` | Signals 辅助 |
44-
| `@lessjs/rpc` | Fetch RPC |
45-
| `@lessjs/create` | 项目脚手架 |
37+
| 包 | 职责 |
38+
| ------------------------- | ---------------------------------------------------------------------- |
39+
| `@lessjs/core` | DSD 渲染器、Renderer Protocol、CEM 解析器、兼容性分类器、manifest 验证 |
40+
| `@lessjs/adapter-vite` | Vite 编排、路由扫描、SSG 管线、CEM 自动检测 |
41+
| `@lessjs/adapter-lit` | Lit TemplateResult → DSD HTML |
42+
| `@lessjs/adapter-react` | React 适配器 |
43+
| `@lessjs/adapter-vanilla` | Vanilla JS 适配器 |
44+
| `@lessjs/app` | 统一入口 `lessjs()` |
45+
| `@lessjs/content` | Blog、Nav、Sitemap 插件 |
46+
| `@lessjs/i18n` | 国际化路由 |
47+
| `@lessjs/ui` | Web Components 组件库 |
48+
| `@lessjs/signals` | Signals 辅助 |
49+
| `@lessjs/rpc` | Fetch RPC |
50+
| `@lessjs/create` | 项目脚手架 CLI |
4651

4752
## 渲染管线
4853

@@ -54,16 +59,32 @@ render() → RenderAdapter → renderDSD() → DSD HTML → SSG → 浏览器解
5459
dsd-interactive → 绑定 hydrateEvents
5560
```
5661

57-
## 路线图
62+
## 第三方包兼容性管线 (v0.18.x)
5863

59-
| 版本 | 目标 | 状态 |
60-
| ----- | ------------------------ | ------ |
61-
| v0.15 | Renderer Kernel Protocol | 开发中 |
62-
| v0.16 | WC Package Protocol | 规划中 |
63-
| v0.17 | Ecosystem Entry | 规划中 |
64-
| v1.0 | API Freeze | 远期 |
64+
```
65+
node_modules/*/custom-elements.json → CEM Parser → 4级分类器 → SSR admission
66+
↓
67+
less validate-manifest (CLI)
68+
↓
69+
less add (安全安装)
70+
```
71+
72+
## 路线图
6573

66-
详见 [ADR-0024](docs/adr/README.md) 和 [ADR-0025](docs/adr/0025-renderer-protocol.md)。
74+
| 版本 | 目标 | 状态 |
75+
| ------- | ------------------------------- | --------- |
76+
| v0.15 | Renderer Kernel Protocol | ✅ 完成 |
77+
| v0.16 | WC Package Protocol | ✅ 完成 |
78+
| v0.17 | Ecosystem Entry + SSR边界 | ✅ 完成 |
79+
| v0.18 | **Universal WC Engine** | **当前** |
80+
| v0.18.0 | CEM 解析器 + 4级分类 + 自动检测 | ✅ 完成 |
81+
| v0.18.1 | validate-manifest CLI | ✅ 完成 |
82+
| v0.18.2 | less add 安全安装流 | ✅ 完成 |
83+
| v0.18.3 | DOM 模拟实验（计划） | 📋 计划中 |
84+
| v0.19 | Registry Hub + Platform | 📋 计划中 |
85+
| v1.0 | API Freeze | 🚀 远期 |
86+
87+
详见 [ADR 文档](docs/adr/) 和 [官方文档](https://lessjs.org)。
6788

6889
## 治理文档
6990

‎docs/changelog/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ One file per version: `vX.Y.Z.md`
3030

3131
| Version | Date | File |
3232
| ------------- | ---------- | ------------------------------------------------ |
33+
| 0.18.2 | 2026-05-17 | [v0.18.2.md](./v0.18.2.md) |
3334
| 0.18.1 | 2026-05-17 | [v0.18.1.md](./v0.18.1.md) |
3435
| 0.18.0 | 2026-05-17 | [v0.18.0.md](./v0.18.0.md) |
3536
| 0.17.5 | 2026-05-17 | [v0.17.5.md](./v0.17.5.md) |

‎docs/changelog/v0.18.2.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Changelog: v0.18.2
2+
3+
> Release date: 2026-05-17
4+
> Release type: **minor patch (CLI + project mutation)**
5+
6+
## Overview
7+
8+
v0.18.2 adds `less add` — a safe install flow for adding third-party Web
9+
Component packages to LessJS projects. Every install is preceded by
10+
validation (v0.18.1), so invalid packages are rejected before any files
11+
are touched.
12+
13+
## What's New
14+
15+
### Safe Install Flow (`@lessjs/core/less-add`)
16+
17+
New module `packages/core/src/less-add.ts` with plan-based install logic:
18+
19+
```
20+
Flow: Resolve → Validate → Plan → Review → Apply
21+
```
22+
23+
### Dry Run First
24+
25+
```sh
26+
less add @scope/package --dry-run
27+
```
28+
29+
Prints the full plan without changing any files:
30+
31+
- Package source and version
32+
- Compatibility tier
33+
- Tags to register
34+
- File mutations (add/modify/remove)
35+
- Warnings and rejected tags
36+
37+
### Validation Gate
38+
39+
Before any file mutation, the v0.18.1 validator is run. If the manifest
40+
fails validation, the add stops immediately with zero file changes.
41+
42+
### File Mutations Generated
43+
44+
For a valid SSR-capable package, the plan includes:
45+
46+
| File | Change |
47+
| --------------------- | ----------------------------------------------- |
48+
| `vite.config.ts` | Add to `packageIslands` array |
49+
| `vite.config.ts` | Add to `ssr.noExternal` list (SSR-capable only) |
50+
| `src/less-imports.ts` | Create/update client registration |
51+
52+
### Compatibility-Aware Behavior
53+
54+
| Tier | Behavior |
55+
| ------------- | ------------------------------------------------------ |
56+
| `ssr-capable` | Full setup: packageIslands + noExternal + registration |
57+
| `client-only` | packageIslands + registration only (no noExternal) |
58+
| `rejected` | No mutations — validation error stops the flow |
59+
60+
### Rollback Safety
61+
62+
If any write fails, the plan prints:
63+
64+
- Which files were changed
65+
- Recovery command or manual rollback instructions
66+
- Does not continue to build
67+
68+
## New Public API
69+
70+
Added to `@lessjs/core`:
71+
72+
**Types**:
73+
74+
- `AddPlan` — full install plan with tags, mutations, status
75+
- `AddTagEntry` — per-tag entry in the install plan
76+
- `FileMutation` — single file change descriptor
77+
- `PackageSource` — local / jsr / npm
78+
79+
**Functions**:
80+
81+
- `generateAddPlan(options)` — generate an install plan for a package
82+
83+
**Exports**:
84+
85+
- `@lessjs/core/less-add` — install flow module
86+
- `@lessjs/core/cli/less-add` — CLI entry point
87+
88+
## Verification
89+
90+
- [x] `less add ./fixtures/ssr-capable --dry-run` changes no files
91+
- [x] `less add ./fixtures/client-only --dry-run` reports client-only outcome
92+
- [x] invalid package fails before file writes
93+
- [x] real install updates expected files only
94+
- [x] rerunning install is idempotent (same input → same plan)
95+
- [x] uninstall/manual rollback instructions are printed when needed
96+
- [x] `deno task fmt && deno task lint && deno task typecheck`
97+
- [x] `deno task test` (673 tests, 14 new)
98+
- [x] `deno task build`
99+
100+
## Breaking Changes
101+
102+
None. v0.18.2 adds new API surface without modifying existing interfaces.
103+
104+
- New optional exports: `generateAddPlan`
105+
- New optional subpath exports: `@lessjs/core/less-add`, `@lessjs/core/cli/less-add`
106+
- No behavior changes to existing code
107+
108+
## Migration Guide
109+
110+
**For users**: No action needed. v0.18.2 is a drop-in replacement for v0.18.1.
111+
112+
**To add a package**:
113+
114+
```sh
115+
# First, check what would happen
116+
deno run -A jsr:@lessjs/core/cli/less-add @scope/package --dry-run
117+
118+
# Then apply
119+
deno run -A jsr:@lessjs/core/cli/less-add @scope/package
120+
```
121+
122+
## Next Steps
123+
124+
With v0.18.2 complete, the project can now proceed to:
125+
126+
- **v0.18.3**: DOM simulation experiment for client-only components
127+
- See `docs/sop/v0.18.3-dom-simulation-experiment.md`
128+
129+
## Diff Summary
130+
131+
```bash
132+
git diff --stat v0.18.1..v0.18.2
133+
134+
packages/core/__tests__/less-add.test.ts (new, 193 lines)
135+
packages/core/deno.json (2 lines changed)
136+
packages/core/src/cli/less-add.ts (new, 123 lines)
137+
packages/core/src/index.ts (10 lines changed)
138+
packages/core/src/less-add.ts (new, 253 lines)
139+
```
140+
141+
**Stats**:
142+
143+
- 3 new files
144+
- 2 modified files
145+
- 14 new tests (673 total)
146+
- +581 / -0 lines

‎docs/status/STATUS.md‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
> AI assistant: read this file first on every session start.
44
5-
## Current Version: 0.18.1
5+
## Current Version: 0.18.2
66

7-
## Next Planned Version: 0.18.2 (planned)
7+
## Next Planned Version: 0.18.3 (experimental)
88

9-
v0.18.1 validate-manifest CLI is complete. v0.18.2 `less add` install flow is next on the roadmap.
9+
v0.18.2 `less add` install flow complete. v0.18.3 DOM simulation experiment is next.
1010

1111
## Branch Status
1212

@@ -29,13 +29,12 @@ v0.18.1 validate-manifest CLI is complete. v0.18.2 `less add` install flow is ne
2929
| v0.16.0 | `a02feb6` | 2026-05-16 |
3030
| v0.15.3 | `5e06fc9` | 2026-05-16 |
3131

32-
## Last Completed Release: 0.18.1 (2026-05-17)
32+
## Last Completed Release: 0.18.2 (2026-05-17)
3333

34-
- **CEM Manifest Validator**: `validateManifest()` in core with per-tag diagnostics
35-
- **CLI**: `validate-manifest` CLI with human-readable and `--json` output
36-
- **Validation checks**: schema shape, tag names, duplicates, module paths, Less extensions
37-
- **Conservative defaults**: CEM-only → client-only; errors → rejected
38-
- **29 new tests, 659 total**
34+
- **`less add` safe install flow**: dry-run + validation gate + plan generation
35+
- **New types**: `AddPlan`, `AddTagEntry`, `FileMutation`, `PackageSource`
36+
- **Compatibility-aware**: SSR-capable → full setup, client-only → limited, rejected → blocked
37+
- **14 new tests, 673 total**
3938

4039
- **Lint fix**: removed `any` type from parent-with-client-child fixture
4140

‎packages/adapter-lit/deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@lessjs/adapter-lit",
3-
"version": "0.18.1",
3+
"version": "0.18.2",
44
"exports": {
55
".": "./src/index.ts",
66
"./ssr": "./src/ssr.ts",

‎packages/adapter-react/deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@lessjs/adapter-react",
3-
"version": "0.18.1",
3+
"version": "0.18.2",
44
"exports": {
55
".": "./src/index.ts",
66
"./ssr": "./src/ssr.ts",

‎packages/adapter-vanilla/deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@lessjs/adapter-vanilla",
3-
"version": "0.18.1",
3+
"version": "0.18.2",
44
"exports": {
55
".": "./src/index.ts",
66
"./ssr": "./src/ssr.ts",

‎packages/adapter-vite/deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@lessjs/adapter-vite",
3-
"version": "0.18.1",
3+
"version": "0.18.2",
44
"exports": {
55
".": "./src/index.ts",
66
"./build-context": "./src/build-context.ts",

0 commit comments

Comments
 (0)