Skip to content

Commit 958a242

Browse files
LessUpLessUp
committed
Merge branch 'pages-whitepaper-overhaul'
保留 master 的颠覆式重构结果，合并分支的非冲突改动： 新增内容： - OpenSpec 变更包 (2026-05-15-pages-whitepaper-overhaul) - 双语 overview 页面 (academy, api, project-status, research) - 迁移指南 (migration.md) - SVG 架构图 (bitcal-vnext-layers.svg) 冲突处理： - 保留 master 版本：README.md, index.md, style.css, changelog.md - 保留 master 删除：旧版 api/architecture/getting-started 文档
2 parents 7a6f032 + 1310012 commit 958a242

22 files changed

Lines changed: 607 additions & 111 deletions

File tree

‎docs/.vitepress/theme/components/ArchitectureDiagram.vue‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,25 @@ const labels: Record<string, { zh: string; en: string }> = {
2020

2121
<template>
2222
<svg viewBox="0 0 720 260" role="img" :aria-label="lang === 'zh' ? 'BitCal 契约与实现边界' : 'BitCal contract and implementation boundary'">
23+
<!-- 第一层：稳定 include seam，高 44px，中线 y=46 -->
2324
<rect x="28" y="24" width="664" height="44" rx="14" data-fill="surface" />
24-
<text x="56" y="52" fill="currentColor" font-size="21" font-weight="680">{{ labels.stableIncludeSeam[lang] }}</text>
25-
<text x="250" y="52" fill="currentColor" font-size="18">&lt;bitcal/bitcal.hpp&gt;</text>
25+
<text x="56" y="46" fill="currentColor" font-size="19" font-weight="680" dominant-baseline="middle">{{ labels.stableIncludeSeam[lang] }}</text>
26+
<text x="270" y="46" fill="currentColor" font-size="16" opacity="0.72" dominant-baseline="middle">&lt;bitcal/bitcal.hpp&gt;</text>
2627

27-
<rect x="28" y="92" width="664" height="52" rx="14" data-fill="accent" />
28-
<text x="56" y="123" fill="currentColor" font-size="22" font-weight="680">{{ labels.publicModel[lang] }}</text>
29-
<text x="208" y="123" fill="currentColor" font-size="16">{{ labels.publicModelDetail[lang] }}</text>
28+
<!-- 连线：第1层 → 第2层 -->
29+
<path d="M360 68 L360 90" stroke-width="2" fill="none" data-stroke="primary" />
3030

31-
<rect x="28" y="168" width="664" height="52" rx="14" data-fill="surface" />
32-
<text x="56" y="199" fill="currentColor" font-size="22" font-weight="680">{{ labels.detailLayer[lang] }}</text>
33-
<text x="208" y="199" fill="currentColor" font-size="16">{{ labels.detailLayerDetail[lang] }}</text>
31+
<!-- 第二层：公开模型，高 56px，中线 y=118 -->
32+
<rect x="28" y="90" width="664" height="56" rx="14" data-fill="accent" />
33+
<text x="56" y="118" fill="currentColor" font-size="21" font-weight="680" dominant-baseline="middle">{{ labels.publicModel[lang] }}</text>
34+
<text x="196" y="118" fill="currentColor" font-size="14" opacity="0.8" dominant-baseline="middle">{{ labels.publicModelDetail[lang] }}</text>
3435

35-
<path d="M360 68 L360 90" stroke-width="2.5" fill="none" data-stroke="primary" />
36-
<path d="M360 144 L360 166" stroke-width="2.5" fill="none" data-stroke="primary" />
36+
<!-- 连线：第2层 → 第3层 -->
37+
<path d="M360 146 L360 164" stroke-width="2" fill="none" data-stroke="primary" />
38+
39+
<!-- 第三层：detail 层，高 56px，中线 y=192 -->
40+
<rect x="28" y="164" width="664" height="56" rx="14" data-fill="surface" />
41+
<text x="56" y="192" fill="currentColor" font-size="21" font-weight="680" dominant-baseline="middle">{{ labels.detailLayer[lang] }}</text>
42+
<text x="196" y="192" fill="currentColor" font-size="14" opacity="0.72" dominant-baseline="middle">{{ labels.detailLayerDetail[lang] }}</text>
3743
</svg>
3844
</template>

‎docs/.vitepress/theme/components/FigureFrame.vue‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,30 @@
11
<script setup lang="ts">
2+
import { useSlots } from 'vue'
3+
4+
const slots = useSlots()
5+
26
defineProps<{
3-
title: string
7+
title?: string
8+
eyebrow?: string
49
caption?: string
510
}>()
611
</script>
712

813
<template>
9-
<figure class="bitcal-figure">
10-
<div class="bitcal-figure__header">
11-
<strong class="bitcal-figure__title">{{ title }}</strong>
12-
<p v-if="caption" class="bitcal-figure__caption">{{ caption }}</p>
14+
<figure class="bc-figure-frame">
15+
<div v-if="eyebrow || slots.title || title" class="bc-figure-heading">
16+
<p v-if="eyebrow" class="bc-figure-eyebrow">{{ eyebrow }}</p>
17+
<div v-if="slots.title || title" class="bc-figure-title">
18+
<slot name="title">{{ title }}</slot>
19+
</div>
1320
</div>
14-
<div class="bitcal-figure__canvas">
21+
22+
<div class="bc-figure-shell">
1523
<slot />
1624
</div>
25+
26+
<figcaption v-if="slots.caption || caption" class="bc-figure-caption">
27+
<slot name="caption">{{ caption }}</slot>
28+
</figcaption>
1729
</figure>
1830
</template>

‎docs/.vitepress/theme/components/ReadingModelDiagram.vue‎

Lines changed: 32 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -33,30 +33,37 @@ const labels: Record<string, { zh: string; en: string }> = {
3333
</script>
3434

3535
<template>
36-
<svg viewBox="0 0 720 360" preserveAspectRatio="xMidYMid meet" role="img" :aria-label="lang === 'zh' ? 'BitCal 阅读模型图' : 'BitCal reading model diagram'">
37-
<rect x="32" y="28" width="656" height="64" rx="16" data-fill="surface" />
38-
<text x="60" y="67" fill="currentColor" font-size="24" font-weight="700">{{ labels.publicContract[lang] }}</text>
39-
<text x="60" y="92" fill="currentColor" font-size="15">{{ labels.publicContractDetail[lang] }}</text>
40-
41-
<rect x="86" y="142" width="250" height="72" rx="18" data-fill="accent" />
42-
<text x="118" y="181" fill="currentColor" font-size="22" font-weight="650">{{ labels.whitepaper[lang] }}</text>
43-
<text x="118" y="205" fill="currentColor" font-size="14">{{ labels.whitepaperDetail[lang] }}</text>
44-
45-
<rect x="384" y="142" width="250" height="72" rx="18" data-fill="surface" />
46-
<text x="416" y="181" fill="currentColor" font-size="22" font-weight="650">{{ labels.performance[lang] }}</text>
47-
<text x="416" y="205" fill="currentColor" font-size="14">{{ labels.performanceDetail[lang] }}</text>
48-
49-
<rect x="86" y="256" width="250" height="72" rx="18" data-fill="surface" />
50-
<text x="118" y="295" fill="currentColor" font-size="22" font-weight="650">{{ labels.reference[lang] }}</text>
51-
<text x="118" y="319" fill="currentColor" font-size="14">{{ labels.referenceDetail[lang] }}</text>
52-
53-
<rect x="384" y="256" width="250" height="72" rx="18" data-fill="surface" />
54-
<text x="416" y="295" fill="currentColor" font-size="22" font-weight="650">{{ labels.research[lang] }}</text>
55-
<text x="416" y="319" fill="currentColor" font-size="14">{{ labels.researchDetail[lang] }}</text>
56-
57-
<path d="M360 92 L360 128" stroke-width="2.5" fill="none" data-stroke="primary" />
58-
<path d="M360 214 L360 242" stroke-width="2.5" fill="none" data-stroke="muted" />
59-
<path d="M210 214 L210 242" stroke-width="2.5" fill="none" data-stroke="muted" />
60-
<path d="M510 214 L510 242" stroke-width="2.5" fill="none" data-stroke="muted" />
36+
<svg viewBox="0 0 720 380" preserveAspectRatio="xMidYMid meet" role="img" :aria-label="lang === 'zh' ? 'BitCal 阅读模型图' : 'BitCal reading model diagram'">
37+
<!-- 公共契约 / Public contract -->
38+
<rect x="32" y="28" width="656" height="68" rx="16" data-fill="surface" />
39+
<text x="60" y="56" fill="currentColor" font-size="22" font-weight="700" dominant-baseline="auto">{{ labels.publicContract[lang] }}</text>
40+
<text x="60" y="80" fill="currentColor" font-size="14" opacity="0.72">{{ labels.publicContractDetail[lang] }}</text>
41+
42+
<!-- 连线：契约 → 中层 -->
43+
<path d="M360 96 L360 138" stroke-width="2" fill="none" data-stroke="primary" />
44+
45+
<!-- 中层：白皮书 / Whitepaper -->
46+
<rect x="40" y="138" width="296" height="76" rx="16" data-fill="accent" />
47+
<text x="72" y="171" fill="currentColor" font-size="21" font-weight="650">{{ labels.whitepaper[lang] }}</text>
48+
<text x="72" y="196" fill="currentColor" font-size="13" opacity="0.8">{{ labels.whitepaperDetail[lang] }}</text>
49+
50+
<!-- 中层：性能 / Performance -->
51+
<rect x="384" y="138" width="296" height="76" rx="16" data-fill="surface" />
52+
<text x="416" y="171" fill="currentColor" font-size="21" font-weight="650">{{ labels.performance[lang] }}</text>
53+
<text x="416" y="196" fill="currentColor" font-size="13" opacity="0.72">{{ labels.performanceDetail[lang] }}</text>
54+
55+
<!-- 连线：中层 → 底层 -->
56+
<path d="M188 214 L188 258" stroke-width="2" fill="none" data-stroke="muted" />
57+
<path d="M532 214 L532 258" stroke-width="2" fill="none" data-stroke="muted" />
58+
59+
<!-- 底层：参考 / Reference -->
60+
<rect x="40" y="258" width="296" height="76" rx="16" data-fill="surface" />
61+
<text x="72" y="291" fill="currentColor" font-size="21" font-weight="650">{{ labels.reference[lang] }}</text>
62+
<text x="72" y="315" fill="currentColor" font-size="13" opacity="0.72">{{ labels.referenceDetail[lang] }}</text>
63+
64+
<!-- 底层：研究 / Research -->
65+
<rect x="384" y="258" width="296" height="76" rx="16" data-fill="surface" />
66+
<text x="416" y="291" fill="currentColor" font-size="21" font-weight="650">{{ labels.research[lang] }}</text>
67+
<text x="416" y="315" fill="currentColor" font-size="13" opacity="0.72">{{ labels.researchDetail[lang] }}</text>
6168
</svg>
6269
</template>

‎docs/.vitepress/theme/components/ReadingPathGrid.vue‎

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,47 @@
11
<script setup lang="ts">
22
import { withBase } from 'vitepress'
33
4+
export type ReadingPathItem = {
5+
title: string
6+
href: string
7+
summary: string
8+
badge?: string
9+
}
10+
411
defineProps<{
5-
items: Array<{
6-
title: string
7-
href: string
8-
summary: string
9-
detail?: string
10-
}>
12+
items: ReadingPathItem[]
1113
}>()
1214
13-
function resolveHref(href: string): string {
14-
if (/^(https?:)?\/\//.test(href)) {
15+
const externalHrefPattern = /^(?:[a-z]+:)?\/\//i
16+
17+
function resolveReadingPathHref(href: string) {
18+
if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:') || externalHrefPattern.test(href)) {
1519
return href
1620
}
1721
18-
return withBase(href)
22+
const match = href.match(/^([^?#]+)([?#].*)?$/)
23+
const path = match?.[1] ?? href
24+
const suffix = match?.[2] ?? ''
25+
const normalized = path.endsWith('/') || path.endsWith('.html') ? path : `${path}.html`
26+
27+
return withBase(`${normalized}${suffix}`)
1928
}
2029
</script>
2130

2231
<template>
23-
<ol class="bitcal-reading-path" aria-label="Reading path">
24-
<li v-for="(item, index) in items" :key="item.href" class="bitcal-reading-path__item">
25-
<span class="bitcal-reading-path__index">{{ String(index + 1).padStart(2, '0') }}</span>
26-
<div class="bitcal-reading-path__body">
27-
<a :href="resolveHref(item.href)" class="bitcal-reading-path__title">{{ item.title }}</a>
28-
<p class="bitcal-reading-path__summary">{{ item.summary }}</p>
29-
<p v-if="item.detail" class="bitcal-reading-path__detail">{{ item.detail }}</p>
32+
<div class="bc-reading-grid">
33+
<a
34+
v-for="item in items"
35+
:key="item.href"
36+
:href="resolveReadingPathHref(item.href)"
37+
class="bc-reading-card"
38+
>
39+
<div class="bc-reading-card-meta">
40+
<span v-if="item.badge" class="bc-reading-card-badge">{{ item.badge }}</span>
3041
</div>
31-
</li>
32-
</ol>
42+
<div class="bc-reading-card-title">{{ item.title }}</div>
43+
<p class="bc-reading-card-summary">{{ item.summary }}</p>
44+
<span class="bc-reading-card-arrow" aria-hidden="true">→</span>
45+
</a>
46+
</div>
3347
</template>

‎docs/en/academy/overview.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Academy
2+
3+
BitCal Academy explains the mental models behind the vNext redesign before the reader dives into API details.
4+
5+
> **Transitional boundary:** This page is the vNext route map for explanatory material. Some deeper concept-setting references are still retained 3.0-era pages or are pending rewrite, so use the whitepaper and project-status pages as the current contract anchors.
6+
7+
## Read this section if you want to understand
8+
9+
- why BitCal exists
10+
- how the block/view split changes composition
11+
- how SIMD dispatch fits into the public contract
12+
- how to interpret benchmark claims responsibly
13+
14+
## Route from here
15+
16+
- [vNext Whitepaper](/en/architecture/vnext-whitepaper)
17+
- [SIMD Dispatch](/en/architecture/simd-dispatch)
18+
- [Performance Baseline](/en/architecture/performance-baseline)
19+
- [Project Status](/en/project-status/)

‎docs/en/api/overview.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Reference Overview
2+
3+
> **Transitional boundary:** This page is the vNext reference landing page. The deeper reference pages linked from here still retain BitCal 3.0-era `bitarray` material unless they explicitly say vNext, and are being kept as reference snapshots pending rewrite.
4+
5+
## This section documents
6+
7+
- the public model
8+
- the observable algorithm surface
9+
- the backend boundary that remains internal
10+
11+
## Route from here
12+
13+
- Start with [Project Status](/en/project-status/) for support and contract boundaries
14+
- Read the [vNext Whitepaper](/en/architecture/vnext-whitepaper) for the target public model
15+
- Use [Types](/en/api/types), [Core Operations](/en/api/core-operations), and the retained API detail pages as reference inventory until the vNext reference rewrite lands

‎docs/en/getting-started/migration.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Migration Guide
2+
3+
> **Transitional boundary:** This page is the vNext migration route map. Some deeper guides it routes into still retain BitCal 3.0-era `bitarray` details and are kept as reference pages pending rewrite.
4+
5+
## Who should read this
6+
7+
- users coming from the retained `bitarray` era
8+
- users updating install snippets or support assumptions
9+
10+
## What changed
11+
12+
- C++23 is now the design baseline
13+
- the public story centers on block/view/algorithms
14+
- vNext does not promise a code-level compatibility layer
15+
16+
## Route from here
17+
18+
- Use [Project Status](/en/project-status/) for the current support and breaking-change posture
19+
- Use [vNext Whitepaper](/en/architecture/vnext-whitepaper) for the intended public model
20+
- Use [Installation](/en/getting-started/installation) and [Quick Start](/en/getting-started/quickstart) as retained setup references until the vNext rewrite lands

‎docs/en/project-status/index.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Project Status
2+
3+
BitCal is in an explicit vNext redesign phase for a breaking v4.0.0 line, not in a "feature-complete stable library" phase.
4+
5+
## This section defines
6+
7+
- support posture
8+
- maintenance boundaries
9+
- migration expectations
10+
- versioning and breaking-change policy
11+
12+
## Current posture
13+
14+
- C++23 is the public design baseline
15+
- optimization and validation are x86-64-first
16+
- the new public model centers on `bit_block`, `bit_view`, and free algorithms
17+
- vNext does not promise a code-level compatibility layer for the retained `bitarray` API
18+
19+
## Support and maintenance boundaries
20+
21+
### Primary
22+
23+
- Linux x86-64 (GCC / Clang)
24+
- Windows x86-64 (MSVC)
25+
- correctness and benchmark truth for the new public surface
26+
27+
### Secondary
28+
29+
- Linux ARM64
30+
- macOS ARM64
31+
- follow-up Pages whitepaper polish and published performance dashboards
32+
33+
Secondary targets must not receive stronger support or performance claims than the retained validation path supports.
34+
35+
## Repository rules that stay in force
36+
37+
- Active requirements live in `openspec/`
38+
- `<bitcal/bitcal.hpp>` remains the only stable public include seam
39+
- docs, specs, code, benchmarks, and version semantics must move together
40+
- benchmark credibility matters more than premature platform or performance claims
41+
42+
## Single sources of truth
43+
44+
- Active requirements: `openspec/`
45+
- Documentation policy: `docs/README.md`
46+
- Stable public include seam: `<bitcal/bitcal.hpp>`
47+
- Version source: `include/bitcal/config.hpp`
48+
49+
## Current execution order
50+
51+
1. Freeze the vNext contract in OpenSpec
52+
2. Land a compiling C++23 public skeleton
53+
3. Rebuild correctness and benchmark truth around the new surface
54+
4. Optimize x86-64 kernels on top of the rebuilt baseline
55+
5. Publish whitepaper and metrics only after retained evidence exists
56+
57+
## Next steps
58+
59+
- Use [Migration Guide](/en/getting-started/migration) if you are updating from the retained `bitarray` era
60+
- Use [vNext Whitepaper](/en/architecture/vnext-whitepaper) for the intended public model
61+
- Use [Academy](/en/academy/overview) for the explanatory route into the redesign

‎docs/en/research/overview.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Research
2+
3+
This section collects the comparative and reflective material behind the BitCal vNext design.
4+
5+
> **Transitional boundary:** This page is the vNext research landing page. Detailed references and comparative notes are still being consolidated, and some retained material may continue to reflect the 3.0-era surface until the rewrite is complete.
6+
7+
## In this section
8+
9+
- related work
10+
- evolution notes
11+
- references and citations
12+
13+
## Route from here
14+
15+
- [vNext Whitepaper](/en/architecture/vnext-whitepaper)
16+
- [Performance Baseline](/en/architecture/performance-baseline)
17+
- [Project Status](/en/project-status/)

‎docs/index.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ hero:
1414

1515
<script setup>
1616
import { onMounted } from 'vue'
17-
import { useRouter, useData, withBase } from 'vitepress'
17+
import { useRouter, withBase } from 'vitepress'
18+
19+
const router = useRouter()
1820

1921
onMounted(() => {
20-
const router = useRouter()
21-
const lang = navigator.language || navigator.userLanguage
22+
const lang = navigator.language || navigator.userLanguage || ''
2223
const target = lang.startsWith('zh') ? '/zh/' : '/en/'
2324
router.go(withBase(target))
2425
})

0 commit comments

Comments
 (0)