@hia-doc/renderer-html 0.1.7 → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +243 -0
  2. package/dist/index.d.ts +1623 -126
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +829 -159
  5. package/dist/index.js.map +1 -1
  6. package/dist/information-architecture.d.ts +284 -20
  7. package/dist/information-architecture.d.ts.map +1 -1
  8. package/dist/information-architecture.js +42 -15
  9. package/dist/information-architecture.js.map +1 -1
  10. package/dist/portal-ui-locale.d.ts +108 -20
  11. package/dist/portal-ui-locale.d.ts.map +1 -1
  12. package/dist/portal-ui-locale.js +103 -27
  13. package/dist/portal-ui-locale.js.map +1 -1
  14. package/dist/presentation-profile.d.ts +176 -16
  15. package/dist/presentation-profile.d.ts.map +1 -1
  16. package/dist/presentation-profile.js +40 -14
  17. package/dist/presentation-profile.js.map +1 -1
  18. package/dist/route-history.d.ts +193 -0
  19. package/dist/route-history.d.ts.map +1 -0
  20. package/dist/route-history.js +246 -0
  21. package/dist/route-history.js.map +1 -0
  22. package/dist/site-chrome.d.ts +173 -0
  23. package/dist/site-chrome.d.ts.map +1 -0
  24. package/dist/site-chrome.js +187 -0
  25. package/dist/site-chrome.js.map +1 -0
  26. package/dist/site-navigation-chrome.d.ts +36 -0
  27. package/dist/site-navigation-chrome.d.ts.map +1 -0
  28. package/dist/site-navigation-chrome.js +430 -0
  29. package/dist/site-navigation-chrome.js.map +1 -0
  30. package/dist/site-navigation.d.ts +175 -0
  31. package/dist/site-navigation.d.ts.map +1 -0
  32. package/dist/site-navigation.js +176 -0
  33. package/dist/site-navigation.js.map +1 -0
  34. package/dist/site-reading.d.ts +171 -0
  35. package/dist/site-reading.d.ts.map +1 -0
  36. package/dist/site-reading.js +534 -0
  37. package/dist/site-reading.js.map +1 -0
  38. package/dist/source-lines.d.ts +3 -2
  39. package/dist/source-lines.d.ts.map +1 -1
  40. package/dist/source-lines.js +15 -9
  41. package/dist/source-lines.js.map +1 -1
  42. package/dist/theme-assets.d.ts +12 -3
  43. package/dist/theme-assets.d.ts.map +1 -1
  44. package/dist/theme-assets.js.map +1 -1
  45. package/package.json +10 -5
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { type DocumentationProjectRouteHistory } from "./route-history.js";
2
+ import { type DocumentationSiteNavigation } from "./site-navigation.js";
1
3
  import { type BusinessFlowDocumentationProjection, type DocumentationUiLocaleCompletenessReport, type DocumentationSourceCommentContentPolicy, type DocumentationSourceCommentProjection, type HiaDiagnostic, type HiaDocument, type HiaI18nModel } from "@hia-doc/core";
2
4
  import type { GeneratedDocumentationBindingHostProjection } from "@hia-doc/source-linkage";
3
5
  import { type ThemeAssetRouting } from "./theme-assets.js";
@@ -6,43 +8,96 @@ import { type DocumentationPortalInformationArchitectureContract, type Documenta
6
8
  import { PORTAL_PRESENTATION_PROFILE_PATH, type PortalPreparedSourceAsset } from "./presentation-profile.js";
7
9
  import { DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH } from "./portal-ui-locale.js";
8
10
  export * from "./information-architecture.js";
9
- export * from "./portal-ui-locale.js";
11
+ export { DOCUMENTATION_PORTAL_UI_LOCALE_PROFILE_ID, DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH, DOCUMENTATION_PORTAL_UI_LOCALE_SURFACE_ID, DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES, DOCUMENTATION_PORTAL_UI_MESSAGE_IDS, createDocumentationPortalUiLocaleAdoption, resolveDocumentationPortalUiMessage, type DocumentationPortalUiLocaleAdoptionOptions, type DocumentationPortalUiLocaleAdoption } from "./portal-ui-locale.js";
10
12
  export * from "./presentation-profile.js";
13
+ export * from "./site-navigation.js";
14
+ export { DOCUMENTATION_PROJECT_ROUTE_HISTORY_CONTRACT, DOCUMENTATION_PROJECT_ROUTE_HISTORY_CONTRACT_VERSION, assertDocumentationProjectRouteHistory, type DocumentationProjectRouteHistory, type DocumentationProjectRouteHistorySource, type DocumentationProjectRouteHistoryBinding, type DocumentationProjectRouteHistoryAlias, type DocumentationProjectRouteHistoryAnchor, type DocumentationProjectRouteHistoryPath } from "./route-history.js";
11
15
  export { renderThemeAssets, type ThemeAssetRouting } from "./theme-assets.js";
16
+ /**
17
+ * @lang zh-CN HTML输出文件清单的精确版本0.1.0,独立于包、文档及各引用工件版本。
18
+ * @lang en Exact HTML output-manifest version 0.1.0, independent of package, document and referenced-artifact versions.
19
+ */
12
20
  export declare const HIA_RENDER_HTML_MANIFEST_SCHEMA_VERSION = "0.1.0";
13
21
  /**
14
- * 项目导航索引的中性 contract 名称;供静态 portal、搜索与宿主导航消费。
15
- * Neutral project-navigation-index contract name consumed by static portals, search, and host navigation.
22
+ * @lang zh-CN 项目导航索引的中性 contract 名称;供静态 portal、搜索与宿主导航消费。
23
+ * @lang en Neutral project-navigation-index contract name consumed by static portals, search, and host navigation.
16
24
  */
17
25
  export declare const HIA_PROJECT_NAVIGATION_INDEX_CONTRACT = "hia-project-navigation-index";
18
26
  /**
19
- * 项目导航索引的首个草案版本;它独立于 renderer manifest 的文件清单版本。
20
- * First draft version of the project navigation index; independent from the renderer manifest file-list version.
27
+ * @lang zh-CN 项目导航索引的首个草案版本;它独立于 renderer manifest 的文件清单版本。
28
+ * @lang en First draft version of the project navigation index; independent from the renderer manifest file-list version.
21
29
  */
22
30
  export declare const HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION = "0.1.0-draft";
23
31
  /**
24
- * 项目级关系图的中性 contract 名称;用于表达文档入口、源码、生成物与宿主能力之间的关系。
25
- * Neutral project-level relation-graph contract for documentation entries, sources, generated artifacts, and host capabilities.
32
+ * @lang zh-CN 携带显式符号作用域的协调索引版本,旧索引writer保留。
33
+ * @lang en Coordinated index version carrying explicit symbol scopes, retaining the legacy index writer.
34
+ */
35
+ export declare const HIA_PROJECT_SCOPED_NAVIGATION_INDEX_CONTRACT_VERSION = "0.2.0-draft";
36
+ /**
37
+ * @lang zh-CN 项目级关系图的中性 contract 名称;用于表达文档入口、源码、生成物与宿主能力之间的关系。
38
+ * @lang en Neutral project-level relation-graph contract for documentation entries, sources, generated artifacts, and host capabilities.
26
39
  */
27
40
  export declare const HIA_PROJECT_RELATION_GRAPH_CONTRACT = "hia-project-relation-graph";
28
41
  /**
29
- * 项目级关系图的首个草案版本;后续 IDE/DevTools host 会按此 contract 做能力协商。
30
- * First draft version of the project relation graph; future IDE/DevTools hosts negotiate capabilities against this contract.
42
+ * @lang zh-CN 项目级关系图的首个草案版本;后续 IDE/DevTools host 会按此 contract 做能力协商。
43
+ * @lang en First draft version of the project relation graph; future IDE/DevTools hosts negotiate capabilities against this contract.
31
44
  */
32
45
  export declare const HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION = "0.1.0-draft";
46
+ /**
47
+ * @lang zh-CN 宿主可写入的内存文件记录:输出相对路径、正文、MIME及角色;renderer不执行文件写入。
48
+ * @lang en In-memory file record for host-owned writing: output-relative path, contents, MIME and role; the renderer performs no file writes.
49
+ */
33
50
  export interface RenderedHtmlFile {
51
+ /**
52
+ * @lang zh-CN 相对于本次输出根目录的文件路径,由宿主写入者解释。
53
+ * @lang en File path relative to this render's output root, interpreted by the host writer.
54
+ */
34
55
  path: string;
56
+ /**
57
+ * @lang zh-CN 待写出的文本正文,惰性源码查看页可在读取属性时生成。
58
+ * @lang en Text contents to be written, with lazy source-view pages generated when the property is read.
59
+ */
35
60
  contents: string;
61
+ /**
62
+ * @lang zh-CN 文件的媒体类型及适用字符集。
63
+ * @lang en Media type and applicable character encoding of the file.
64
+ */
36
65
  contentType: string;
66
+ /**
67
+ * @lang zh-CN 文件角色,entry为页面入口,asset为静态资源,index为结构化索引。
68
+ * @lang en File role, using entry for page entrypoints, asset for static resources and index for structured indexes.
69
+ */
37
70
  role: "entry" | "asset" | "index";
38
71
  }
72
+ /**
73
+ * @lang zh-CN 文档/项目渲染选项;普通文档保持单页,项目选项仅在对应项目路径消费。默认主题资源包含,locale缺省由文档/项目决定。
74
+ * @lang en Document/project rendering options; documents stay single-page and project options apply only to project paths. Theme assets default on and omitted locale follows document/project metadata.
75
+ */
39
76
  export interface RenderHtmlOptions {
77
+ /**
78
+ * @lang zh-CN 可选的初始正文语言,省略时使用文档或项目解析出的默认语言。
79
+ * @lang en Optional initial content locale, using the document or resolved project default when omitted.
80
+ */
40
81
  locale?: string;
82
+ /**
83
+ * @lang zh-CN 可选的页面标题覆盖,优先于文档标题或项目标题与名称。
84
+ * @lang en Optional page-title override taking precedence over document title or project title and name.
85
+ */
41
86
  title?: string;
87
+ /**
88
+ * @lang zh-CN 是否在本次输出中包含默认主题资源,缺省为true。
89
+ * @lang en Whether to include default-theme assets in this render's output, defaulting to true.
90
+ */
42
91
  includeThemeAssets?: boolean;
43
- /** @lang zh-CN 默认本地资源;external只引用同站共享资源,不越过输出根写文件。 @lang en Defaults to local assets; external references same-site shared assets without writing outside the output root. */
92
+ /**
93
+ * @lang zh-CN 默认本地资源;external只引用同站共享资源,不越过输出根写文件。
94
+ * @lang en Defaults to local assets; external references same-site shared assets without writing outside the output root.
95
+ */
44
96
  themeAssets?: ThemeAssetRouting;
45
- /** @lang zh-CN 普通与项目输出共用的品牌颜色和构建期皮肤/配色,逐项优先于旧projectSite.theme。 @lang en Brand colors and build-time skin/scheme shared by document/project output, taking per-field precedence over legacy projectSite.theme. */
97
+ /**
98
+ * @lang zh-CN 普通与项目输出共用的品牌颜色和构建期皮肤/配色,逐项优先于旧projectSite.theme。
99
+ * @lang en Brand colors and build-time skin/scheme shared by document/project output, taking per-field precedence over legacy projectSite.theme.
100
+ */
46
101
  theme?: RenderHtmlThemeOptions;
47
102
  /**
48
103
  * @lang zh-CN 项目站输出与源码策略;单文档只读取theme作为兼容回退,其余项目策略不适用。
@@ -50,88 +105,193 @@ export interface RenderHtmlOptions {
50
105
  */
51
106
  projectSite?: RenderProjectSiteOptions;
52
107
  }
108
+ /**
109
+ * @lang zh-CN 项目条目的领域分组闭集;all为汇总视图,不声明每个领域已全面支持。
110
+ * @lang en Closed project-entry domain groups; all is an aggregate view, not a claim of complete domain support.
111
+ */
53
112
  export type RenderProjectView = "all" | "js" | "css" | "html" | "dotnet" | "powershell" | "other";
113
+ /**
114
+ * @lang zh-CN 项目站分页布局闭集;默认split-site,single-page为显式兼容选择。
115
+ * @lang en Closed project-site layouts; split-site is the default and single-page an explicit compatibility choice.
116
+ */
54
117
  export type RenderProjectSiteLayout = "split-site" | "single-page";
118
+ /**
119
+ * @lang zh-CN 源码正文/链接呈现策略闭集,默认和公开授权由项目站策略决定。
120
+ * @lang en Closed source body/link presentation policy, with defaults and disclosure authority determined by project-site policy.
121
+ */
55
122
  export type RenderProjectSourcePresentation = "none" | "link" | "embed" | "fetch";
123
+ /**
124
+ * @lang zh-CN 公开同源源码的展开时或手动加载策略,不授权获取任意URL。
125
+ * @lang en On-expand or manual loading of public same-origin source assets, without authorizing arbitrary URLs.
126
+ */
56
127
  export type RenderProjectSourceFetchTrigger = "on-expand" | "manual";
57
- /** @lang zh-CN Portal 的构建时默认 skin/scheme;运行时选择不改变内容 identity。 @lang en Build-time Portal skin/scheme defaults; runtime selection does not change content identity. */
128
+ /**
129
+ * @lang zh-CN Portal 的构建时默认 skin/scheme;运行时选择不改变内容 identity。
130
+ * @lang en Build-time Portal skin/scheme defaults; runtime selection does not change content identity.
131
+ */
58
132
  export interface RenderProjectThemeOptions {
133
+ /**
134
+ * @lang zh-CN 可选的构建期配色方案,共享theme逐项优先,缺省回退system。
135
+ * @lang en Optional build-time color scheme, with shared theme taking per-field precedence and the default falling back to system.
136
+ */
59
137
  scheme?: PortalThemeScheme;
138
+ /**
139
+ * @lang zh-CN 可选的构建期皮肤标识,共享theme逐项优先,缺省回退portal.classic。
140
+ * @lang en Optional build-time skin identifier, with shared theme taking per-field precedence and the default falling back to portal.classic.
141
+ */
60
142
  skinId?: PortalThemeSkinId;
61
143
  }
62
- /** @lang zh-CN 主题owner的安全品牌颜色及既有皮肤/配色,不接收自定义CSS或代码。 @lang en Theme-owner safe brand colors plus existing skin/scheme, without custom CSS or code. */
144
+ /**
145
+ * @lang zh-CN 主题owner的安全品牌颜色及既有皮肤/配色,不接收自定义CSS或代码。
146
+ * @lang en Theme-owner safe brand colors plus existing skin/scheme, without custom CSS or code.
147
+ */
63
148
  export interface RenderHtmlThemeOptions extends RenderProjectThemeOptions, HiaThemeAssetOptions {
64
149
  }
150
+ /**
151
+ * @lang zh-CN 项目站布局、信息架构、语言、主题和源码策略;显式信息架构才启用对应契约投影,不改变canonical条目身份。
152
+ * @lang en Project-site layout, information architecture, locales, theme and source policy; explicit information architecture enables its projections without changing canonical entry identities.
153
+ */
65
154
  export interface RenderProjectSiteOptions {
66
- /** 默认 split-site;single-page 仅适合兼容、小型文档或静态快照。Defaults to split-site; single-page is for compatibility, small docs, or snapshots. */
155
+ /**
156
+ * @lang zh-CN 可选独立0.1.0-draft站点导航;须显式uiLocale,在首写前校验/复制,覆盖完整页面且不扩大源码授权。
157
+ * @lang en Optional independent 0.1.0-draft site navigation, requiring explicit uiLocale and validated/snapshotted before the first write, covering complete pages without additional source authority.
158
+ */
159
+ siteNavigation?: DocumentationSiteNavigation;
160
+ /**
161
+ * @lang zh-CN 可选显式发布历史,固定页面身份并恢复已公开旧地址,不授予源码读取。
162
+ * @lang en Optional explicit publication history pinning page identity and recovering published routes without source-read authority.
163
+ */
164
+ routeHistory?: DocumentationProjectRouteHistory;
165
+ /**
166
+ * @lang zh-CN 默认 split-site;single-page 仅适合兼容、小型文档或静态快照。
167
+ * @lang en Defaults to split-site; single-page is for compatibility, small docs, or snapshots.
168
+ */
67
169
  layout?: RenderProjectSiteLayout;
68
170
  /**
69
- * 显式 IA 才启用 P4 slice;缺失时保持 P3 output path。
70
- * Only explicit IA enables the P4 slice; omission preserves the P3 output path.
171
+ * @lang zh-CN 显式 IA 才启用 P4 slice;缺失时保持 P3 output path。
172
+ * @lang en Only explicit IA enables the P4 slice; omission preserves the P3 output path.
71
173
  */
72
174
  informationArchitecture?: DocumentationPortalInformationArchitectureOptions;
73
- /** UI chrome locale,与 project content locale 独立。UI chrome locale, independent from the project content locale. */
175
+ /**
176
+ * @lang zh-CN UI chrome locale,与 project content locale 独立。
177
+ * @lang en UI chrome locale, independent from the project content locale.
178
+ */
74
179
  uiLocale?: DocumentationPortalUiLocale;
75
180
  /**
76
- * @lang zh-CN
77
- * W-P123 report 的 owner-neutral profile/surface identity;仅显式 IA 消费,译文与 DOM 结构不进入该 descriptor。
181
+ * @lang zh-CN W-P123 report 的 owner-neutral profile/surface identity;仅显式 IA 消费,译文与 DOM 结构不进入该 descriptor。
78
182
  *
79
- * @lang en
80
- * Owner-neutral profile/surface identity for the W-P123 report; consumed only by explicit IA and carries no translation or DOM structure.
183
+ * @lang en Owner-neutral profile/surface identity for the W-P123 report; consumed only by explicit IA and carries no translation or DOM structure.
81
184
  */
82
185
  uiLocaleCompleteness?: RenderProjectUiLocaleCompletenessOptions;
83
186
  /**
84
- * @lang zh-CN
85
- * source-comment locale 与正文授权;只有显式 IA 下才消费,且不从 UI/content locale 推断。
187
+ * @lang zh-CN source-comment locale 与正文授权;只有显式 IA 下才消费,且不从 UI/content locale 推断。
86
188
  *
87
- * @lang en
88
- * Source-comment locale and body authorization, consumed only under explicit IA and never inferred from UI or content locale.
189
+ * @lang en Source-comment locale and body authorization, consumed only under explicit IA and never inferred from UI or content locale.
89
190
  */
90
191
  sourceCommentProjection?: RenderProjectSourceCommentProjectionOptions;
91
- /** @lang zh-CN Portal-owned skin 与独立 scheme 选择。 @lang en Portal-owned skin and independent scheme selection. */
192
+ /**
193
+ * @lang zh-CN Portal-owned skin 与独立 scheme 选择。
194
+ * @lang en Portal-owned skin and independent scheme selection.
195
+ */
92
196
  theme?: RenderProjectThemeOptions;
197
+ /**
198
+ * @lang zh-CN 项目源码正文、链接及加载策略,呈现方式缺省为fetch,资源来自调用方授权的内存预览。
199
+ * @lang en Project source-body, link and loading policies, defaulting presentation to fetch and taking assets from caller-authorized in-memory previews.
200
+ */
93
201
  source?: {
94
- /** 控制源码正文与链接是否进入输出。Controls whether source bodies or links enter the output. */
202
+ /**
203
+ * @lang zh-CN 控制源码正文与链接是否进入输出。
204
+ * @lang en Controls whether source bodies or links enter the output.
205
+ */
95
206
  presentation?: RenderProjectSourcePresentation;
96
- /** embed 模式的源码详情默认展开状态。Default expansion state for embedded source details. */
207
+ /**
208
+ * @lang zh-CN embed 模式的源码详情默认展开状态。
209
+ * @lang en Default expansion state for embedded source details.
210
+ */
97
211
  defaultExpanded?: boolean;
98
- /** fetch 模式默认在展开时加载;manual 保留显式加载按钮。Fetch mode loads on expansion by default; manual keeps an explicit load button. */
212
+ /**
213
+ * @lang zh-CN fetch 模式默认在展开时加载;manual 保留显式加载按钮。
214
+ * @lang en Fetch mode loads on expansion by default; manual keeps an explicit load button.
215
+ */
99
216
  fetchTrigger?: RenderProjectSourceFetchTrigger;
100
- /** fetch 模式单次最多显示的源码行数。Maximum source lines displayed by one fetch operation. */
217
+ /**
218
+ * @lang zh-CN fetch 模式单次最多显示的源码行数。
219
+ * @lang en Maximum source lines displayed by one fetch operation.
220
+ */
101
221
  maxLines?: number;
102
222
  };
103
223
  }
104
- /** @lang zh-CN Portal UI locale report 的可覆盖 identity。 @lang en Overridable identities for the Portal UI-locale report. */
224
+ /**
225
+ * @lang zh-CN Portal UI locale report 的可覆盖 identity。
226
+ * @lang en Overridable identities for the Portal UI-locale report.
227
+ */
105
228
  export interface RenderProjectUiLocaleCompletenessOptions {
229
+ /**
230
+ * @lang zh-CN 可选的已登记界面完整性profile身份,默认portal.default。
231
+ * @lang en Optional registered UI-completeness profile identity, defaulting to portal.default.
232
+ */
106
233
  profileId?: string;
234
+ /**
235
+ * @lang zh-CN 可选的已登记界面面身份,默认portal.split-site,须与profileId精确配对。
236
+ * @lang en Optional registered surface identity, defaulting to portal.split-site and required to pair exactly with profileId.
237
+ */
107
238
  surfaceId?: string;
108
239
  }
109
240
  /**
110
- * @lang zh-CN
111
- * Portal P5 有界 slice 的 runtime 选项;P1 不支持 rich text 或 source fetch。
241
+ * @lang zh-CN Portal P5 有界 slice 的 runtime 选项;P1 不支持 rich text 或 source fetch。
112
242
  *
113
- * @lang en
114
- * Runtime options for the bounded Portal P5 slice; P1 supports neither rich text nor source fetch.
243
+ * @lang en Runtime options for the bounded Portal P5 slice; P1 supports neither rich text nor source fetch.
115
244
  */
116
245
  export interface RenderProjectSourceCommentProjectionOptions {
246
+ /**
247
+ * @lang zh-CN 源码注释投影正文的消费策略,默认none;纯文本正文还须生产方投影同时授权。
248
+ * @lang en Consumption policy for projected source-comment text, defaulting to none, with plain text also requiring authorization in the producer projection.
249
+ */
117
250
  contentPolicy?: DocumentationSourceCommentContentPolicy;
251
+ /**
252
+ * @lang zh-CN 调用方显式指定的规范BCP 47注释语言,须与条目投影requestedLocale一致。
253
+ * @lang en Canonical BCP 47 comment locale explicitly supplied by the caller, required to match each entry projection's requestedLocale.
254
+ */
118
255
  locale: string;
119
256
  }
257
+ /**
258
+ * @lang zh-CN 调用方已聚合的项目、条目及可选关系/投影;renderer不自行发现文件或认证owner输入事实。
259
+ * @lang en Caller-aggregated project, entries and optional relations/projections; the renderer neither discovers files nor attests owner-input facts.
260
+ */
120
261
  export interface RenderProjectHtmlInput {
262
+ /**
263
+ * @lang zh-CN 调用方提供的项目身份、标题和语言元数据。
264
+ * @lang en Caller-supplied project identity, title and locale metadata.
265
+ */
121
266
  project: RenderProjectInfo;
267
+ /**
268
+ * @lang zh-CN 已聚合的项目文档条目,稳定标识及文件名投影须唯一。
269
+ * @lang en Aggregated project documentation entries whose stable identifiers and filename projections must be unique.
270
+ */
122
271
  entries: RenderProjectEntry[];
272
+ /**
273
+ * @lang zh-CN 可选的已使用文档化配置规范引用集合。
274
+ * @lang en Optional collection of references to documentation profiles used by the project.
275
+ */
123
276
  profiles?: RenderProjectProfileRef[];
277
+ /**
278
+ * @lang zh-CN 可选的文档源码映射工件引用与计数摘要。
279
+ * @lang en Optional documentation source-map artifact references and count summaries.
280
+ */
124
281
  docSourceMaps?: RenderProjectDocSourceMapRef[];
125
282
  /**
126
- * 中文:由 @hia-doc/source-linkage 的 W-P52.5 index 产生的安全 binding relation 投影。
127
- * English: Safe binding-relation projection produced by the W-P52.5
128
- * @hia-doc/source-linkage index.
283
+ * @lang zh-CN 由 @hia-doc/source-linkage 的 W-P52.5 index 产生的安全 binding relation 投影。
284
+ * @lang en Safe binding-relation projection produced by the W-P52.5 @hia-doc/source-linkage index.
129
285
  */
130
286
  generatedDocumentationBindingProjection?: GeneratedDocumentationBindingHostProjection;
287
+ /**
288
+ * @lang zh-CN 可选的显式关系图,提供时规范排序并重算计数,缺省时从现有条目关联构造。
289
+ * @lang en Optional explicit relation graph, sorted and recounted when provided and otherwise constructed from existing entry associations.
290
+ */
131
291
  relationGraph?: RenderProjectRelationGraph;
132
292
  /**
133
- * optional、body-free 的 W-P84 continuity 摘要;renderer 不读取 report 文件或 target state。
134
- * Optional body-free W-P84 continuity summary; the renderer reads neither report files nor target state.
293
+ * @lang zh-CN optional、body-free 的 W-P84 continuity 摘要;renderer 不读取 report 文件或 target state。
294
+ * @lang en Optional body-free W-P84 continuity summary; the renderer reads neither report files nor target state.
135
295
  */
136
296
  documentationContinuity?: RenderProjectDocumentationContinuitySummary;
137
297
  /**
@@ -140,48 +300,128 @@ export interface RenderProjectHtmlInput {
140
300
  */
141
301
  ownerAdoption?: RenderProjectOwnerAdoptionSummary;
142
302
  /**
143
- * @lang zh-CN
144
- * optional W-P122 public dual projection;W-P124 只将其投影到 Portal structured data plane,不据此定稿可见 flow UI。
303
+ * @lang zh-CN optional W-P122 public dual projection;W-P124 只将其投影到 Portal structured data plane,不据此定稿可见 flow UI。
145
304
  *
146
- * @lang en
147
- * Optional W-P122 public dual projection; W-P124 projects it only to the Portal structured data plane and does not finalize a visible flow UI from it.
305
+ * @lang en Optional W-P122 public dual projection; W-P124 projects it only to the Portal structured data plane and does not finalize a visible flow UI from it.
148
306
  */
149
307
  businessFlowDocumentationProjection?: BusinessFlowDocumentationProjection;
308
+ /**
309
+ * @lang zh-CN 调用方提供的项目级诊断集合。
310
+ * @lang en Collection of project-level diagnostics supplied by the caller.
311
+ */
150
312
  diagnostics?: HiaDiagnostic[];
151
313
  }
314
+ /**
315
+ * @lang zh-CN 项目的可公开身份、标题、语言和产品版本;产品版本仅作metadata,不参与路由。
316
+ * @lang en Public project identity, title, locales and product version; product version is metadata only and never participates in routing.
317
+ */
152
318
  export interface RenderProjectInfo {
319
+ /**
320
+ * @lang zh-CN 可选的项目稳定标识,缺省按project:前缀与项目名称构造。
321
+ * @lang en Optional stable project identifier, defaulting to the project: prefix followed by the project name.
322
+ */
153
323
  id?: string;
324
+ /**
325
+ * @lang zh-CN 必需的公开项目名称,也是缺省项目身份和标题的输入。
326
+ * @lang en Required public project name, also used to derive the default project identity and title.
327
+ */
154
328
  name: string;
329
+ /**
330
+ * @lang zh-CN 可选的项目显示标题,缺省使用name,可由渲染选项title覆盖。
331
+ * @lang en Optional project display title, defaulting to name and overridable by the render option title.
332
+ */
155
333
  title?: string;
156
334
  /**
157
- * 项目页面的默认语言;若未提供则从已声明语言或 `und` 推断。
158
- * Default project-page locale; inferred from declared locales or `und` when omitted.
335
+ * @lang zh-CN 项目页面的默认语言;若未提供则从已声明语言或 `und` 推断。
336
+ * @lang en Default project-page locale; inferred from declared locales or `und` when omitted.
159
337
  */
160
338
  defaultLocale?: string;
161
339
  /**
162
- * 项目聚合页中可切换的语言。
163
- * Locales that can be switched within the project aggregation page.
340
+ * @lang zh-CN 项目聚合页中可切换的语言。
341
+ * @lang en Locales that can be switched within the project aggregation page.
164
342
  */
165
343
  locales?: string[];
166
- /** 产品版本仅呈现为 metadata,不参与 route。Product version is displayed as metadata and never participates in routing. */
344
+ /**
345
+ * @lang zh-CN 产品版本仅呈现为 metadata,不参与 route。
346
+ * @lang en Product version is displayed as metadata and never participates in routing.
347
+ */
167
348
  productVersion?: string;
168
349
  }
169
- /** Portal 可消费的最小 continuity summary;不携带 target identity、path、entry id 或正文。Minimal Portal continuity summary without target identity, paths, entry ids, or bodies. */
350
+ /**
351
+ * @lang zh-CN Portal 可消费的最小 continuity summary;不携带 target identity、path、entry id 或正文。
352
+ * @lang en Minimal Portal continuity summary without target identity, paths, entry ids, or bodies.
353
+ */
170
354
  export interface RenderProjectDocumentationContinuitySummary {
355
+ /**
356
+ * @lang zh-CN 固定的target-documentation-continuity契约名称。
357
+ * @lang en Fixed target-documentation-continuity contract name.
358
+ */
171
359
  contract: "target-documentation-continuity";
360
+ /**
361
+ * @lang zh-CN 固定的0.1.0-draft精确连续性摘要版本。
362
+ * @lang en Fixed exact 0.1.0-draft continuity-summary version.
363
+ */
172
364
  contractVersion: "0.1.0-draft";
365
+ /**
366
+ * @lang zh-CN 调用方提供的accepted或refused连续性结果。
367
+ * @lang en Caller-supplied accepted or refused continuity result.
368
+ */
173
369
  status: "accepted" | "refused";
370
+ /**
371
+ * @lang zh-CN 基线、当前、增加、移除和未变条目数量,必须满足集合计数等式。
372
+ * @lang en Counts of baseline, current, added, removed and unchanged entries, required to satisfy collection-count equations.
373
+ */
174
374
  entries: {
375
+ /**
376
+ * @lang zh-CN 相对基线新增的条目数量,与unchangedCount相加须等于currentCount。
377
+ * @lang en Number of entries added since the baseline, whose sum with unchangedCount must equal currentCount.
378
+ */
175
379
  addedCount: number;
380
+ /**
381
+ * @lang zh-CN 基线条目数量,须等于unchangedCount加removedCount。
382
+ * @lang en Baseline entry count, required to equal unchangedCount plus removedCount.
383
+ */
176
384
  baselineCount: number;
385
+ /**
386
+ * @lang zh-CN 当前条目数量,须等于unchangedCount加addedCount。
387
+ * @lang en Current entry count, required to equal unchangedCount plus addedCount.
388
+ */
177
389
  currentCount: number;
390
+ /**
391
+ * @lang zh-CN 相对基线移除的条目数量。
392
+ * @lang en Number of entries removed since the baseline.
393
+ */
178
394
  removedCount: number;
395
+ /**
396
+ * @lang zh-CN 基线与当前集合中保留未变的条目数量。
397
+ * @lang en Number of unchanged entries retained between the baseline and current collections.
398
+ */
179
399
  unchangedCount: number;
180
400
  };
401
+ /**
402
+ * @lang zh-CN 调用方声明必需输出是否保留,渲染器仅消费摘要。
403
+ * @lang en Caller declaration of whether required outputs were preserved, consumed by the renderer as a summary only.
404
+ */
181
405
  requiredOutputsPreserved: boolean;
406
+ /**
407
+ * @lang zh-CN 分别记录解析状态、调用方未核置信度及元数据比较来源。
408
+ * @lang en Separate records of resolution state, caller-provided unverified confidence and metadata-comparison provenance.
409
+ */
182
410
  semantics: {
411
+ /**
412
+ * @lang zh-CN 调用方记录的证据与摘要配对已校验状态或unresolved。
413
+ * @lang en Caller-recorded evidence/summary-pair validation state or unresolved.
414
+ */
183
415
  resolution: "evidence-summary-pair-validated" | "unresolved";
416
+ /**
417
+ * @lang zh-CN 固定为caller-provided-unverified,保留调用方提供但未由渲染器认证的置信边界。
418
+ * @lang en Fixed to caller-provided-unverified, preserving the boundary of caller data not attested by the renderer.
419
+ */
184
420
  confidence: "caller-provided-unverified";
421
+ /**
422
+ * @lang zh-CN 固定为metadata-only-comparison,来源仅为元数据比较。
423
+ * @lang en Fixed to metadata-only-comparison, limiting provenance to metadata comparison.
424
+ */
185
425
  provenance: "metadata-only-comparison";
186
426
  };
187
427
  }
@@ -190,111 +430,421 @@ export interface RenderProjectDocumentationContinuitySummary {
190
430
  * @lang en Minimal Portal-consumable owner-adoption projection without target/trial/owner identity, paths, bodies, or adoption claims.
191
431
  */
192
432
  export interface RenderProjectOwnerAdoptionSummary {
433
+ /**
434
+ * @lang zh-CN 固定的target-owner-adoption-kit契约名称。
435
+ * @lang en Fixed target-owner-adoption-kit contract name.
436
+ */
193
437
  contract: "target-owner-adoption-kit";
438
+ /**
439
+ * @lang zh-CN 固定的0.1.0-draft精确负责人审阅摘要版本。
440
+ * @lang en Fixed exact 0.1.0-draft owner-review summary version.
441
+ */
194
442
  contractVersion: "0.1.0-draft";
443
+ /**
444
+ * @lang zh-CN 固定为portal-metadata-only,仅向Portal提供元数据投影。
445
+ * @lang en Fixed to portal-metadata-only, providing only a metadata projection to the Portal.
446
+ */
195
447
  projection: "portal-metadata-only";
448
+ /**
449
+ * @lang zh-CN 负责人审阅准备状态,记录待审阅、缺输入延期或拒绝。
450
+ * @lang en Owner-review readiness state recording readiness, deferral for missing input or refusal.
451
+ */
196
452
  status: "ready-for-owner-review" | "deferred-owner-input-missing" | "refused";
453
+ /**
454
+ * @lang zh-CN 调用方声明的enterprise-business或workspace-container目标族。
455
+ * @lang en Caller-declared enterprise-business or workspace-container target family.
456
+ */
197
457
  targetFamily: "enterprise-business" | "workspace-container";
458
+ /**
459
+ * @lang zh-CN 负责人输入是否提交及审阅同意记录状态。
460
+ * @lang en Submission state of owner input and the recorded review-consent state.
461
+ */
198
462
  ownerInput: {
463
+ /**
464
+ * @lang zh-CN 负责人材料是否已提交,ready-for-owner-review要求为true。
465
+ * @lang en Whether owner materials were submitted, required to be true for ready-for-owner-review.
466
+ */
199
467
  submitted: boolean;
468
+ /**
469
+ * @lang zh-CN 仅记录未登记或已登记审阅同意的状态。
470
+ * @lang en Records only whether review consent is unrecorded or recorded.
471
+ */
200
472
  consent: "not-recorded" | "recorded-for-review";
201
473
  };
474
+ /**
475
+ * @lang zh-CN 必需、已提供与缺失契约的非负整数计数。
476
+ * @lang en Non-negative integer counts of required, provided and missing contracts.
477
+ */
202
478
  contracts: {
479
+ /**
480
+ * @lang zh-CN 必需契约数量,须等于providedCount加missingCount。
481
+ * @lang en Required contract count, required to equal providedCount plus missingCount.
482
+ */
203
483
  requiredCount: number;
484
+ /**
485
+ * @lang zh-CN 调用方已提供的契约数量。
486
+ * @lang en Number of contracts supplied by the caller.
487
+ */
204
488
  providedCount: number;
489
+ /**
490
+ * @lang zh-CN 仍缺失的契约数量,ready-for-owner-review要求为0。
491
+ * @lang en Number of contracts still missing, required to be zero for ready-for-owner-review.
492
+ */
205
493
  missingCount: number;
206
494
  };
495
+ /**
496
+ * @lang zh-CN 工作区容器目标可用的交接计数与待负责人审阅状态,ready时必须提供。
497
+ * @lang en Handoff counts and pending-owner-review state for workspace-container targets, required when ready.
498
+ */
207
499
  workspaceHandoff?: {
500
+ /**
501
+ * @lang zh-CN 参与工作区交接的仓库负责人数量,提供交接记录时至少为2。
502
+ * @lang en Number of repository owners participating in workspace handoff, at least two when a handoff record is supplied.
503
+ */
208
504
  repositoryOwnerCount: number;
505
+ /**
506
+ * @lang zh-CN 工作区交接关系数量,提供交接记录时至少为1。
507
+ * @lang en Number of workspace handoff edges, at least one when a handoff record is supplied.
508
+ */
209
509
  handoffEdgeCount: number;
510
+ /**
511
+ * @lang zh-CN 固定为owner-review-required,表示交接仍待负责人审阅。
512
+ * @lang en Fixed to owner-review-required, indicating that handoff still requires owner review.
513
+ */
210
514
  state: "owner-review-required";
211
515
  };
516
+ /**
517
+ * @lang zh-CN 分别记录输入解析状态、未核置信度及负责人材料元数据来源。
518
+ * @lang en Separate records of input-resolution state, unverified confidence and owner-kit metadata provenance.
519
+ */
212
520
  semantics: {
521
+ /**
522
+ * @lang zh-CN 负责人输入已校验、尚未收到或unresolved的独立解析状态。
523
+ * @lang en Independent resolution state for validated owner input, input not received or unresolved.
524
+ */
213
525
  resolution: "owner-input-validated" | "owner-input-not-received" | "unresolved";
526
+ /**
527
+ * @lang zh-CN 固定为caller-provided-unverified,渲染器不认证调用方材料真实性。
528
+ * @lang en Fixed to caller-provided-unverified, with the renderer performing no attestation of caller-material authenticity.
529
+ */
214
530
  confidence: "caller-provided-unverified";
531
+ /**
532
+ * @lang zh-CN 固定为metadata-only-owner-kit,来源仅为负责人材料元数据。
533
+ * @lang en Fixed to metadata-only-owner-kit, limiting provenance to owner-kit metadata.
534
+ */
215
535
  provenance: "metadata-only-owner-kit";
216
536
  };
217
537
  }
538
+ /**
539
+ * @lang zh-CN 已用文档化配置规范的轻量引用;profileVersion与包/规范根版本独立,path仅作来源metadata。
540
+ * @lang en Lightweight reference to a used documentation profile; profileVersion is independent of package/root versions and path is provenance metadata only.
541
+ */
218
542
  export interface RenderProjectProfileRef {
543
+ /**
544
+ * @lang zh-CN 已使用文档化配置规范的稳定标识。
545
+ * @lang en Stable identifier of a documentation profile used by the project.
546
+ */
219
547
  profileId: string;
548
+ /**
549
+ * @lang zh-CN 可选的文档化配置规范版本,独立于包版本及规范根版本。
550
+ * @lang en Optional documentation-profile version, independent of package and specification-root versions.
551
+ */
220
552
  profileVersion?: string;
553
+ /**
554
+ * @lang zh-CN 可选的配置规范层标识,用于分组与来源显示。
555
+ * @lang en Optional profile-layer identifier used for grouping and provenance display.
556
+ */
221
557
  layer?: string;
558
+ /**
559
+ * @lang zh-CN 可选的配置规范来源路径,仅作元数据引用。
560
+ * @lang en Optional profile-origin path used solely as a metadata reference.
561
+ */
222
562
  path?: string;
223
563
  }
564
+ /**
565
+ * @lang zh-CN 文档源码映射文件的版本、计数和关联摘要,不含源码正文;计数由上游提供,不作为权限或精度证明。
566
+ * @lang en Version, counts and linkage summary for a documentation source-map file without source bodies; upstream counts prove neither authority nor coordinate precision.
567
+ */
224
568
  export interface RenderProjectDocSourceMapRef {
569
+ /**
570
+ * @lang zh-CN 地图所属的可选聚合作用域,不授予源码读取权限。
571
+ * @lang en Optional aggregate scope owning this map, granting no source-read authority.
572
+ */
573
+ identityScope?: string;
574
+ /**
575
+ * @lang zh-CN 上游提供的生成工件数量摘要。
576
+ * @lang en Upstream-provided count summary of generated artifacts.
577
+ */
225
578
  artifactCount?: number;
579
+ /**
580
+ * @lang zh-CN 被引用文档源码映射工件的路径,仅作元数据。
581
+ * @lang en Path of the referenced documentation source-map artifact, used only as metadata.
582
+ */
226
583
  path: string;
584
+ /**
585
+ * @lang zh-CN 上游文档源码映射工件的可选精确版本标签。
586
+ * @lang en Optional exact version label of the upstream documentation source-map artifact.
587
+ */
227
588
  contractVersion?: string;
589
+ /**
590
+ * @lang zh-CN 可选的入口生成工件标识或路径摘要。
591
+ * @lang en Optional identifier or path summary of the entry generated artifact.
592
+ */
228
593
  entryArtifact?: string;
594
+ /**
595
+ * @lang zh-CN 上游提供的映射条目总数。
596
+ * @lang en Total mapping-entry count supplied upstream.
597
+ */
229
598
  entryCount?: number;
599
+ /**
600
+ * @lang zh-CN 上游报告已关联的映射条目数量。
601
+ * @lang en Number of linked mapping entries reported upstream.
602
+ */
230
603
  linkedEntryCount?: number;
604
+ /**
605
+ * @lang zh-CN 上游提供的源码记录数量。
606
+ * @lang en Number of source records supplied upstream.
607
+ */
231
608
  sourceCount?: number;
609
+ /**
610
+ * @lang zh-CN 可选的普通位置映射引用集合,不内嵌映射内容。
611
+ * @lang en Optional ordinary position-map references, without embedding map contents.
612
+ */
232
613
  sourceMaps?: RenderProjectSourceMapRef[];
614
+ /**
615
+ * @lang zh-CN 上游提供的普通位置映射数量摘要。
616
+ * @lang en Upstream-provided count summary of ordinary position maps.
617
+ */
233
618
  sourceMapCount?: number;
619
+ /**
620
+ * @lang zh-CN 上游记录的源码正文策略标签,摘要本身不授予读取权限。
621
+ * @lang en Upstream-recorded source-body policy label, with the summary itself granting no read permission.
622
+ */
234
623
  sourcesContentPolicy?: string;
624
+ /**
625
+ * @lang zh-CN 上游提供的映射关联状态摘要。
626
+ * @lang en Upstream-provided summary of mapping-linkage status.
627
+ */
235
628
  status?: string;
629
+ /**
630
+ * @lang zh-CN 上游报告尚未解析的映射条目数量。
631
+ * @lang en Number of unresolved mapping entries reported upstream.
632
+ */
236
633
  unresolvedEntryCount?: number;
237
634
  }
635
+ /**
636
+ * @lang zh-CN 普通位置映射的轻量身份/路径/语言引用;不内嵌映射段或授权读取文件。
637
+ * @lang en Lightweight identity/path/language reference to an ordinary position map, without embedded mappings or file-read authority.
638
+ */
238
639
  export interface RenderProjectSourceMapRef {
640
+ /**
641
+ * @lang zh-CN 普通位置映射的稳定引用标识。
642
+ * @lang en Stable reference identifier of an ordinary position map.
643
+ */
239
644
  id: string;
645
+ /**
646
+ * @lang zh-CN 可选的位置映射类别标签。
647
+ * @lang en Optional position-map kind label.
648
+ */
240
649
  kind?: string;
650
+ /**
651
+ * @lang zh-CN 可选的位置映射所属语言标签。
652
+ * @lang en Optional language label associated with the position map.
653
+ */
241
654
  language?: string;
655
+ /**
656
+ * @lang zh-CN 可选的位置映射文件路径,仅作引用。
657
+ * @lang en Optional position-map file path used only as a reference.
658
+ */
242
659
  path?: string;
243
660
  }
661
+ /**
662
+ * @lang zh-CN 项目关系节点的entry/source/artifact/endpoint闭集,不授权对相应目标执行动作。
663
+ * @lang en Closed entry/source/artifact/endpoint relation-node kinds, without authorizing actions on those targets.
664
+ */
244
665
  export type RenderProjectRelationNodeKind = "entry" | "source" | "artifact" | "endpoint";
666
+ /**
667
+ * @lang zh-CN 项目关系语义闭集,表达文档/源码/生成物/端点/成员关联,不推断额外关系。
668
+ * @lang en Closed project-relation semantics for documentation/source/artifact/endpoint/member links, without inferring additional relationships.
669
+ */
245
670
  export type RenderProjectRelationKind = "documents-source" | "documents-generated-artifact" | "documents-endpoint" | "exposes-api" | "semantic-member";
246
671
  /**
247
- * 统一项目页与外部宿主共同消费的轻量关系图。
248
- * Lightweight relation graph shared by the unified project page and external hosts.
672
+ * @lang zh-CN 统一项目页与外部宿主共同消费的轻量关系图。
673
+ * @lang en Lightweight relation graph shared by the unified project page and external hosts.
249
674
  */
250
675
  export interface RenderProjectRelationGraph {
676
+ /**
677
+ * @lang zh-CN 项目关系图契约身份,规范化时写入hia-project-relation-graph。
678
+ * @lang en Project relation-graph contract identity, written as hia-project-relation-graph during normalization.
679
+ */
251
680
  contract: typeof HIA_PROJECT_RELATION_GRAPH_CONTRACT;
681
+ /**
682
+ * @lang zh-CN 项目关系图版本,规范化时写入0.1.0-draft。
683
+ * @lang en Project relation-graph version, written as 0.1.0-draft during normalization.
684
+ */
252
685
  contractVersion: typeof HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION;
686
+ /**
687
+ * @lang zh-CN 节点数量,规范化时按nodes长度重新计算。
688
+ * @lang en Node count, recomputed from the length of nodes during normalization.
689
+ */
253
690
  nodeCount: number;
691
+ /**
692
+ * @lang zh-CN 关系数量,规范化时按relations长度重新计算。
693
+ * @lang en Relation count, recomputed from the length of relations during normalization.
694
+ */
254
695
  relationCount: number;
696
+ /**
697
+ * @lang zh-CN 项目关系节点集合,规范化时复制并稳定排序。
698
+ * @lang en Project relation-node collection, copied and stably sorted during normalization.
699
+ */
255
700
  nodes: RenderProjectRelationNode[];
701
+ /**
702
+ * @lang zh-CN 有方向的项目关系集合,规范化时复制并稳定排序。
703
+ * @lang en Directed project-relation collection, copied and stably sorted during normalization.
704
+ */
256
705
  relations: RenderProjectRelation[];
257
706
  }
258
707
  /**
259
- * relation graph 中的稳定节点;节点可以代表文档入口、源码、生成物或运行时端点。
260
- * Stable node in the relation graph; it can represent a documentation entry, source, generated artifact, or runtime endpoint.
708
+ * @lang zh-CN relation graph 中的稳定节点;节点可以代表文档入口、源码、生成物或运行时端点。
709
+ * @lang en Stable node in the relation graph; it can represent a documentation entry, source, generated artifact, or runtime endpoint.
261
710
  */
262
711
  export interface RenderProjectRelationNode {
712
+ /**
713
+ * @lang zh-CN 图中此节点的稳定标识,供关系端点引用。
714
+ * @lang en Stable identifier of this graph node, referenced by relation endpoints.
715
+ */
263
716
  id: string;
717
+ /**
718
+ * @lang zh-CN 节点表示的文档条目、源码、生成物或端点类别。
719
+ * @lang en Kind of entity represented by the node, covering documentation entry, source, artifact or endpoint.
720
+ */
264
721
  kind: RenderProjectRelationNodeKind;
722
+ /**
723
+ * @lang zh-CN 节点的可公开显示标签。
724
+ * @lang en Public display label of the node.
725
+ */
265
726
  label: string;
727
+ /**
728
+ * @lang zh-CN 可选的关联文档条目标识。
729
+ * @lang en Optional associated documentation-entry identifier.
730
+ */
266
731
  entryId?: string;
732
+ /**
733
+ * @lang zh-CN 可选的源码或生成物路径元数据。
734
+ * @lang en Optional source or generated-artifact path metadata.
735
+ */
267
736
  path?: string;
737
+ /**
738
+ * @lang zh-CN 可选的领域视图分组。
739
+ * @lang en Optional domain-view grouping.
740
+ */
268
741
  view?: RenderProjectView;
269
742
  }
270
743
  /**
271
- * relation graph 中的一条方向关系;第一轮仅表达统一页面和宿主导航需要的最小关系。
272
- * Directed relation in the graph; the first slice covers the minimal relationships needed by unified pages and host navigation.
744
+ * @lang zh-CN relation graph 中的一条方向关系;第一轮仅表达统一页面和宿主导航需要的最小关系。
745
+ * @lang en Directed relation in the graph; the first slice covers the minimal relationships needed by unified pages and host navigation.
273
746
  */
274
747
  export interface RenderProjectRelation {
748
+ /**
749
+ * @lang zh-CN 有向关系的稳定标识。
750
+ * @lang en Stable identifier of the directed relation.
751
+ */
275
752
  id: string;
753
+ /**
754
+ * @lang zh-CN 文档与源码、生成物、端点或成员之间的闭集关系语义。
755
+ * @lang en Closed-set relation semantics linking documentation with source, generated artifacts, endpoints or members.
756
+ */
276
757
  kind: RenderProjectRelationKind;
758
+ /**
759
+ * @lang zh-CN 关系来源图节点的标识。
760
+ * @lang en Identifier of the relation's source graph node.
761
+ */
277
762
  from: string;
763
+ /**
764
+ * @lang zh-CN 关系目标图节点的标识。
765
+ * @lang en Identifier of the relation's target graph node.
766
+ */
278
767
  to: string;
768
+ /**
769
+ * @lang zh-CN 关系的可公开显示标签。
770
+ * @lang en Public display label of the relation.
771
+ */
279
772
  label: string;
773
+ /**
774
+ * @lang zh-CN 可选的上游关系置信度标签,独立于引用解析。
775
+ * @lang en Optional upstream relation-confidence label, independent of reference resolution.
776
+ */
280
777
  confidence?: string;
778
+ /**
779
+ * @lang zh-CN 可选的关联文档条目标识。
780
+ * @lang en Optional associated documentation-entry identifier.
781
+ */
281
782
  entryId?: string;
783
+ /**
784
+ * @lang zh-CN 可选的公开标量元数据,仅允许字符串、数字、布尔值或null。
785
+ * @lang en Optional public scalar metadata restricted by type to strings, numbers, booleans or null.
786
+ */
282
787
  metadata?: Record<string, string | number | boolean | null>;
283
788
  }
789
+ /**
790
+ * @lang zh-CN 结构化项目条目及可选本地化、来源和关系摘要;身份由输入提供,正文/源码公开须经过相应owner与呈现策略验证。
791
+ * @lang en Structured project entry with optional localization, source and relation summaries; inputs own identities and body/source disclosure requires owner and presentation-policy validation.
792
+ */
284
793
  export interface RenderProjectEntry {
794
+ /**
795
+ * @lang zh-CN 可选发布安全聚合作用域,保留原生symbolId且不授权源码读取。
796
+ * @lang en Optional publication-safe aggregation scope, preserving native symbolId and granting no source-read authority.
797
+ */
798
+ identityScope?: string;
799
+ /**
800
+ * @lang zh-CN 调用方提供的稳定条目标识,用于规范片段路由及主题身份。
801
+ * @lang en Caller-supplied stable entry identifier used for canonical fragment routes and topic identity.
802
+ */
285
803
  id: string;
804
+ /**
805
+ * @lang zh-CN 条目的公开显示名称与搜索输入。
806
+ * @lang en Public display name and search input of the entry.
807
+ */
286
808
  name: string;
809
+ /**
810
+ * @lang zh-CN 领域生产方提供的条目语义类别。
811
+ * @lang en Semantic entry kind supplied by the domain producer.
812
+ */
287
813
  kind: string;
814
+ /**
815
+ * @lang zh-CN 条目所属的领域视图分组。
816
+ * @lang en Domain-view grouping containing the entry.
817
+ */
288
818
  view: RenderProjectView;
819
+ /**
820
+ * @lang zh-CN 缺少主i18n字段时使用的可选摘要正文。
821
+ * @lang en Optional summary text used when the primary i18n field is absent.
822
+ */
289
823
  summary?: string;
824
+ /**
825
+ * @lang zh-CN 可选的声明签名,按转义代码文本呈现。
826
+ * @lang en Optional declaration signature rendered as escaped code text.
827
+ */
290
828
  signature?: string;
291
829
  /**
292
- * 从领域 adapter/core symbol 透传的字段级 i18n;description 会驱动项目页的语言切换。
293
- * Field-level i18n forwarded from a domain adapter/core symbol; description drives project-page locale switching.
830
+ * @lang zh-CN 从领域 adapter/core symbol 透传的字段级 i18n;description 会驱动项目页的语言切换。
831
+ * @lang en Field-level i18n forwarded from a domain adapter/core symbol; description drives project-page locale switching.
294
832
  */
295
833
  i18n?: HiaI18nModel;
834
+ /**
835
+ * @lang zh-CN 可选的条目文档化配置规范引用。
836
+ * @lang en Optional documentation-profile reference for the entry.
837
+ */
296
838
  profile?: RenderProjectProfileRef;
839
+ /**
840
+ * @lang zh-CN 可选的来源输入工件元数据。
841
+ * @lang en Optional metadata of the originating input artifact.
842
+ */
297
843
  input?: RenderProjectInputRef;
844
+ /**
845
+ * @lang zh-CN 可选的源码定位及已授权预览输入,受项目源码策略处理。
846
+ * @lang en Optional source-location and authorized-preview input, processed under project source policy.
847
+ */
298
848
  source?: RenderProjectSourceRef;
299
849
  /**
300
850
  * @lang zh-CN source relation 到 canonical entry 的 metadata-only 可用性投影;不授予源码读取能力。
@@ -302,83 +852,295 @@ export interface RenderProjectEntry {
302
852
  */
303
853
  sourceUsability?: RenderProjectSourceUsabilityRef;
304
854
  /**
305
- * @lang zh-CN
306
- * 已由 owner producer 生成并通过中性 contract 校验的 source-comment projection。
855
+ * @lang zh-CN 已由 owner producer 生成并通过中性 contract 校验的 source-comment projection。
307
856
  *
308
- * @lang en
309
- * Source-comment projection already produced by an owner producer and validated against the neutral contract.
857
+ * @lang en Source-comment projection already produced by an owner producer and validated against the neutral contract.
310
858
  */
311
859
  sourceCommentProjection?: DocumentationSourceCommentProjection;
860
+ /**
861
+ * @lang zh-CN 可选的上游规范符号标识,用于层级关联。
862
+ * @lang en Optional upstream canonical symbol identifier used for hierarchy linkage.
863
+ */
312
864
  symbolId?: string;
865
+ /**
866
+ * @lang zh-CN 可选的领域语义层级,由上游显式提供。
867
+ * @lang en Optional domain-semantic hierarchy explicitly supplied upstream.
868
+ */
313
869
  hierarchy?: RenderProjectEntryHierarchyRef;
870
+ /**
871
+ * @lang zh-CN 可选的条目到文档源码映射关联摘要。
872
+ * @lang en Optional summary linking the entry to a documentation source map.
873
+ */
314
874
  docSourceMap?: RenderProjectEntryDocSourceMapRef;
875
+ /**
876
+ * @lang zh-CN 可选的条目级诊断集合。
877
+ * @lang en Optional collection of entry-level diagnostics.
878
+ */
315
879
  diagnostics?: HiaDiagnostic[];
316
- /** manifest input 显式提供的 owner-reviewed semantic prefix。Owner-reviewed semantic prefix explicitly supplied by the manifest input. */
880
+ /**
881
+ * @lang zh-CN manifest input 显式提供的 owner-reviewed semantic prefix。
882
+ * @lang en Owner-reviewed semantic prefix explicitly supplied by the manifest input.
883
+ */
317
884
  semanticPath?: DocumentationPortalSemanticPathSegment[];
318
885
  }
319
886
  /**
320
- * 领域 adapter 或 source relation 提供的稳定语义层级,renderer 只投影、不重新猜测语言语义。
321
- * Stable semantic hierarchy supplied by a domain adapter or source relation; the renderer only projects it.
887
+ * @lang zh-CN 领域 adapter 或 source relation 提供的稳定语义层级,renderer 只投影、不重新猜测语言语义。
888
+ * @lang en Stable semantic hierarchy supplied by a domain adapter or source relation; the renderer only projects it.
322
889
  */
323
890
  export interface RenderProjectEntryHierarchyRef {
891
+ /**
892
+ * @lang zh-CN 可选的所属程序集名称。
893
+ * @lang en Optional containing assembly name.
894
+ */
324
895
  assembly?: string;
896
+ /**
897
+ * @lang zh-CN 可选的所属命名空间。
898
+ * @lang en Optional containing namespace.
899
+ */
325
900
  namespace?: string;
901
+ /**
902
+ * @lang zh-CN 可选的所属类型名称或上游类型标识。
903
+ * @lang en Optional containing type name or upstream type identifier.
904
+ */
326
905
  containingType?: string;
906
+ /**
907
+ * @lang zh-CN 可选的领域文档符号标识,例如.NET文档ID。
908
+ * @lang en Optional domain documentation-symbol identifier, such as a .NET documentation ID.
909
+ */
327
910
  symbolDocumentationId?: string;
911
+ /**
912
+ * @lang zh-CN 可选的层级显示名称。
913
+ * @lang en Optional hierarchy display name.
914
+ */
328
915
  displayName?: string;
916
+ /**
917
+ * @lang zh-CN 可选的显式父符号标识,按条目symbolId解析父项。
918
+ * @lang en Optional explicit parent-symbol identifier resolved against entry symbolId values.
919
+ */
329
920
  parentSymbolId?: string;
921
+ /**
922
+ * @lang zh-CN 可选的基类型标识集合。
923
+ * @lang en Optional collection of base-type identifiers.
924
+ */
330
925
  baseTypeIds?: string[];
926
+ /**
927
+ * @lang zh-CN 可选的实现接口标识集合。
928
+ * @lang en Optional collection of implemented-interface identifiers.
929
+ */
331
930
  interfaceIds?: string[];
332
931
  }
932
+ /**
933
+ * @lang zh-CN 条目到文档源码映射的轻量关联及来源/产物摘要;不代替共享reader的范围/列单位精确查询。
934
+ * @lang en Lightweight entry-to-documentation-map linkage and source/artifact summary, without replacing precise range/column-unit queries in the shared reader.
935
+ */
333
936
  export interface RenderProjectEntryDocSourceMapRef {
937
+ /**
938
+ * @lang zh-CN 可选的上游生成物匹配置信度标签。
939
+ * @lang en Optional upstream generated-artifact match-confidence label.
940
+ */
334
941
  artifactConfidence?: string;
942
+ /**
943
+ * @lang zh-CN 可选的关联生成物路径摘要。
944
+ * @lang en Optional path summary of the associated generated artifact.
945
+ */
335
946
  artifactPath?: string;
947
+ /**
948
+ * @lang zh-CN 可选的生成物节点选择器,仅作为定位元数据。
949
+ * @lang en Optional generated-artifact node selector used only as location metadata.
950
+ */
336
951
  artifactSelector?: string;
952
+ /**
953
+ * @lang zh-CN 可选的上游映射诊断码集合。
954
+ * @lang en Optional collection of upstream mapping diagnostic codes.
955
+ */
337
956
  diagnostics?: string[];
957
+ /**
958
+ * @lang zh-CN 被关联文档源码映射中的条目标识。
959
+ * @lang en Entry identifier within the associated documentation source map.
960
+ */
338
961
  entryId: string;
962
+ /**
963
+ * @lang zh-CN 文档源码映射工件的引用路径。
964
+ * @lang en Reference path of the documentation source-map artifact.
965
+ */
339
966
  path: string;
967
+ /**
968
+ * @lang zh-CN 可选的上游源码定位置信度标签。
969
+ * @lang en Optional upstream source-location confidence label.
970
+ */
340
971
  sourceConfidence?: string;
972
+ /**
973
+ * @lang zh-CN 可选的原始源码路径摘要。
974
+ * @lang en Optional original-source path summary.
975
+ */
341
976
  sourcePath?: string;
977
+ /**
978
+ * @lang zh-CN 可选的上游源码范围摘要,终点约定与列单位按对应映射契约解释。
979
+ * @lang en Optional upstream source-range summary, with endpoint conventions and column units interpreted under the corresponding map contract.
980
+ */
342
981
  sourceRange?: {
982
+ /**
983
+ * @lang zh-CN 范围的一基起始位置,由上游定位信息提供。
984
+ * @lang en One-based start position of the range, supplied by upstream location metadata.
985
+ */
343
986
  start: {
987
+ /**
988
+ * @lang zh-CN 上游提供的一基源码行号。
989
+ * @lang en One-based source-line number supplied upstream.
990
+ */
344
991
  line: number;
992
+ /**
993
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
994
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
995
+ */
345
996
  column?: number;
346
997
  };
998
+ /**
999
+ * @lang zh-CN 可选的范围结束位置,其终点语义由对应上游契约规定。
1000
+ * @lang en Optional range end position, whose endpoint semantics are defined by the corresponding upstream contract.
1001
+ */
347
1002
  end?: {
1003
+ /**
1004
+ * @lang zh-CN 上游提供的一基源码行号。
1005
+ * @lang en One-based source-line number supplied upstream.
1006
+ */
348
1007
  line: number;
1008
+ /**
1009
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
1010
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
1011
+ */
349
1012
  column?: number;
350
1013
  };
351
1014
  };
1015
+ /**
1016
+ * @lang zh-CN 可选的源码范围来源标签,保留上游来源语义。
1017
+ * @lang en Optional source-range origin label preserving upstream provenance semantics.
1018
+ */
352
1019
  sourceRangeSource?: string;
353
1020
  }
1021
+ /**
1022
+ * @lang zh-CN 输入工件的kind/path及可选精确契约引用,仅作溯源,不读取或自动迁移所指文件。
1023
+ * @lang en Input-artifact kind/path and optional exact contract reference for provenance only, without reading or automatically migrating the referenced file.
1024
+ */
354
1025
  export interface RenderProjectInputRef {
1026
+ /**
1027
+ * @lang zh-CN 输入工件类别标签。
1028
+ * @lang en Input-artifact kind label.
1029
+ */
355
1030
  kind: string;
1031
+ /**
1032
+ * @lang zh-CN 来源输入工件的路径元数据。
1033
+ * @lang en Path metadata of the originating input artifact.
1034
+ */
356
1035
  path: string;
1036
+ /**
1037
+ * @lang zh-CN 可选的稳定输入工件标识。
1038
+ * @lang en Optional stable input-artifact identifier.
1039
+ */
357
1040
  artifactId?: string;
1041
+ /**
1042
+ * @lang zh-CN 可选的输入工件契约名称。
1043
+ * @lang en Optional input-artifact contract name.
1044
+ */
358
1045
  contract?: string;
1046
+ /**
1047
+ * @lang zh-CN 可选的输入工件精确版本标签。
1048
+ * @lang en Optional exact version label of the input artifact.
1049
+ */
359
1050
  contractVersion?: string;
360
1051
  }
1052
+ /**
1053
+ * @lang zh-CN 源码定位和已授权公开资产/预览的输入引用;本地path不自动公开正文,fetch/link使用构建生成的同源资产。
1054
+ * @lang en Source-location reference and authorized public asset/preview inputs; a local path never automatically discloses bodies, and fetch/link use build-generated same-origin assets.
1055
+ */
361
1056
  export interface RenderProjectSourceRef {
1057
+ /**
1058
+ * @lang zh-CN 可选的上游源码引用置信度标签。
1059
+ * @lang en Optional upstream source-reference confidence label.
1060
+ */
362
1061
  confidence?: string;
1062
+ /**
1063
+ * @lang zh-CN 构建期生成的同源纯文本资源URL;调用方旧URL在源码策略阶段被剥离。
1064
+ * @lang en Build-generated same-origin plain-text asset URL, with legacy caller URLs stripped during source-policy processing.
1065
+ */
363
1066
  fetchUrl?: string;
1067
+ /**
1068
+ * @lang zh-CN 可选的fetch触发方式,项目级配置优先,缺省为on-expand。
1069
+ * @lang en Optional fetch trigger, overridden by project-level configuration and defaulting to on-expand.
1070
+ */
364
1071
  fetchTrigger?: RenderProjectSourceFetchTrigger;
1072
+ /**
1073
+ * @lang zh-CN 可选的fetch显示行数上限,项目级配置优先,缺省为400。
1074
+ * @lang en Optional fetched-source display line limit, overridden by project-level configuration and defaulting to 400.
1075
+ */
365
1076
  fetchMaxLines?: number;
1077
+ /**
1078
+ * @lang zh-CN 可选的源码语言标签。
1079
+ * @lang en Optional source-language label.
1080
+ */
366
1081
  language?: string;
1082
+ /**
1083
+ * @lang zh-CN 构建期生成的同源源码查看链接;调用方旧外链在源码策略阶段被剥离。
1084
+ * @lang en Build-generated same-origin source-view link, with legacy caller external links stripped during source-policy processing.
1085
+ */
367
1086
  linkUrl?: string;
1087
+ /**
1088
+ * @lang zh-CN 用于公开位置显示及稳定源码身份构造的路径元数据。
1089
+ * @lang en Path metadata used for public location display and stable source-identity construction.
1090
+ */
368
1091
  path: string;
369
- /** @lang zh-CN renderer 构造的 body-free public asset metadata;正文只存在于单独静态文件。 @lang en Body-free public-asset metadata built by the renderer; the body exists only in a separate static file. */
1092
+ /**
1093
+ * @lang zh-CN renderer 构造的 body-free public asset metadata;正文只存在于单独静态文件。
1094
+ * @lang en Body-free public-asset metadata built by the renderer; the body exists only in a separate static file.
1095
+ */
370
1096
  publicAsset?: PortalPreparedSourceAsset;
1097
+ /**
1098
+ * @lang zh-CN 可选的调用方源码预览正文及范围,须遵守公开授权与呈现策略。
1099
+ * @lang en Optional caller-supplied source-preview body and range, subject to disclosure authorization and presentation policy.
1100
+ */
371
1101
  preview?: RenderProjectSourcePreviewRef;
1102
+ /**
1103
+ * @lang zh-CN 可选的上游源码位置范围摘要,独立于预览正文范围。
1104
+ * @lang en Optional upstream source-location range summary, independent of the preview body's range.
1105
+ */
372
1106
  range?: {
1107
+ /**
1108
+ * @lang zh-CN 范围的一基起始位置,由上游定位信息提供。
1109
+ * @lang en One-based start position of the range, supplied by upstream location metadata.
1110
+ */
373
1111
  start: {
1112
+ /**
1113
+ * @lang zh-CN 上游提供的一基源码行号。
1114
+ * @lang en One-based source-line number supplied upstream.
1115
+ */
374
1116
  line: number;
1117
+ /**
1118
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
1119
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
1120
+ */
375
1121
  column?: number;
376
1122
  };
1123
+ /**
1124
+ * @lang zh-CN 可选的范围结束位置,其终点语义由对应上游契约规定。
1125
+ * @lang en Optional range end position, whose endpoint semantics are defined by the corresponding upstream contract.
1126
+ */
377
1127
  end?: {
1128
+ /**
1129
+ * @lang zh-CN 上游提供的一基源码行号。
1130
+ * @lang en One-based source-line number supplied upstream.
1131
+ */
378
1132
  line: number;
1133
+ /**
1134
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
1135
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
1136
+ */
379
1137
  column?: number;
380
1138
  };
381
1139
  };
1140
+ /**
1141
+ * @lang zh-CN 可选的源码位置范围来源标签。
1142
+ * @lang en Optional provenance label for the source-location range.
1143
+ */
382
1144
  rangeSource?: string;
383
1145
  }
384
1146
  /**
@@ -386,11 +1148,20 @@ export interface RenderProjectSourceRef {
386
1148
  * @lang en Project-relative source identity; both ID and path are owner-producer resolved and must not derive from a display label, locale, or absolute path.
387
1149
  */
388
1150
  export interface RenderProjectSourceProjectIdentityRef {
389
- /** @lang zh-CN owner producer 生成的稳定 project ID。 @lang en Stable project ID generated by the owner producer. */
1151
+ /**
1152
+ * @lang zh-CN owner producer 生成的稳定 project ID。
1153
+ * @lang en Stable project ID generated by the owner producer.
1154
+ */
390
1155
  id: string;
391
- /** @lang zh-CN 工作区相对 `.csproj` path;不得为绝对路径。 @lang en Workspace-relative `.csproj` path; never an absolute path. */
1156
+ /**
1157
+ * @lang zh-CN 工作区相对 `.csproj` path;不得为绝对路径。
1158
+ * @lang en Workspace-relative `.csproj` path; never an absolute path.
1159
+ */
392
1160
  path: string;
393
- /** @lang zh-CN 生成 ID/path 的 identity policy。 @lang en Identity policy used to produce the ID and path. */
1161
+ /**
1162
+ * @lang zh-CN 生成 ID/path 的 identity policy。
1163
+ * @lang en Identity policy used to produce the ID and path.
1164
+ */
394
1165
  policy: string;
395
1166
  }
396
1167
  /**
@@ -398,46 +1169,152 @@ export interface RenderProjectSourceProjectIdentityRef {
398
1169
  * @lang en Bounded Portal projection of a source relation; resolution, confidence, and provenance remain independent while privacy stays metadata-only.
399
1170
  */
400
1171
  export interface RenderProjectSourceUsabilityRef {
401
- /** @lang zh-CN 上游 relation artifact 中的稳定 relation ID。 @lang en Stable relation ID from the upstream relation artifact. */
1172
+ /**
1173
+ * @lang zh-CN 上游 relation artifact 中的稳定 relation ID。
1174
+ * @lang en Stable relation ID from the upstream relation artifact.
1175
+ */
402
1176
  relationId: string;
403
- /** @lang zh-CN 引用是否已解析;与 confidence、provenance 独立。 @lang en Whether the reference resolved; independent from confidence and provenance. */
1177
+ /**
1178
+ * @lang zh-CN 引用是否已解析;与 confidence、provenance 独立。
1179
+ * @lang en Whether the reference resolved; independent from confidence and provenance.
1180
+ */
404
1181
  resolution: string;
405
- /** @lang zh-CN relation 可信度;不替代 resolution。 @lang en Relation confidence; it does not replace resolution. */
1182
+ /**
1183
+ * @lang zh-CN relation 可信度;不替代 resolution。
1184
+ * @lang en Relation confidence; it does not replace resolution.
1185
+ */
406
1186
  confidence: string;
407
- /** @lang zh-CN 产生 relation 的 producer、activity 与 contract identity。 @lang en Producer, activity, and contract identity that created the relation. */
1187
+ /**
1188
+ * @lang zh-CN 产生 relation 的 producer、activity 与 contract identity。
1189
+ * @lang en Producer, activity, and contract identity that created the relation.
1190
+ */
408
1191
  provenance: {
1192
+ /**
1193
+ * @lang zh-CN 生成上游源码关系的生产器标识。
1194
+ * @lang en Identifier of the producer that generated the upstream source relation.
1195
+ */
409
1196
  producer: string;
1197
+ /**
1198
+ * @lang zh-CN 生成上游源码关系的活动标识。
1199
+ * @lang en Identifier of the activity that generated the upstream source relation.
1200
+ */
410
1201
  activity: string;
1202
+ /**
1203
+ * @lang zh-CN 上游源码关系来源契约名称。
1204
+ * @lang en Contract name of the upstream source-relation provenance.
1205
+ */
411
1206
  contract: string;
1207
+ /**
1208
+ * @lang zh-CN 上游源码关系来源契约的版本标签。
1209
+ * @lang en Version label of the upstream source-relation provenance contract.
1210
+ */
412
1211
  contractVersion: string;
413
1212
  };
414
- /** @lang zh-CN projectPath 驱动时存在的稳定项目身份。 @lang en Stable project identity present when projectPath drove extraction. */
1213
+ /**
1214
+ * @lang zh-CN projectPath 驱动时存在的稳定项目身份。
1215
+ * @lang en Stable project identity present when projectPath drove extraction.
1216
+ */
415
1217
  projectIdentity?: RenderProjectSourceProjectIdentityRef;
416
- /** @lang zh-CN Portal 投影的固定 metadata-only privacy boundary。 @lang en Fixed metadata-only privacy boundary of the Portal projection. */
1218
+ /**
1219
+ * @lang zh-CN Portal 投影的固定 metadata-only privacy boundary。
1220
+ * @lang en Fixed metadata-only privacy boundary of the Portal projection.
1221
+ */
417
1222
  privacy: {
1223
+ /**
1224
+ * @lang zh-CN 固定为none,此可用性投影不携带sourcesContent。
1225
+ * @lang en Fixed to none, excluding sourcesContent from this usability projection.
1226
+ */
418
1227
  sourcesContentPolicy: "none";
1228
+ /**
1229
+ * @lang zh-CN 固定为none,此可用性投影不提供源码预览正文。
1230
+ * @lang en Fixed to none, excluding source-preview bodies from this usability projection.
1231
+ */
419
1232
  sourcePreviewPolicy: "none";
1233
+ /**
1234
+ * @lang zh-CN 固定为false,此可用性投影不嵌入源码正文。
1235
+ * @lang en Fixed to false, preventing this usability projection from embedding source bodies.
1236
+ */
420
1237
  embedsSourcesContent: false;
421
1238
  };
422
1239
  }
1240
+ /**
1241
+ * @lang zh-CN 调用方提供的源码预览正文、语言和一基范围;存在该结构不等于已获公开授权。
1242
+ * @lang en Caller-provided source-preview body, language and one-based range; its presence is not disclosure authorization.
1243
+ */
423
1244
  export interface RenderProjectSourcePreviewRef {
1245
+ /**
1246
+ * @lang zh-CN 调用方在内存中提供的预览正文,仅按显式源码策略消费并转义呈现。
1247
+ * @lang en Preview body supplied in memory by the caller, consumed only under explicit source policy and rendered with escaping.
1248
+ */
424
1249
  content: string;
1250
+ /**
1251
+ * @lang zh-CN 可选的内嵌预览默认展开状态,项目级defaultExpanded优先。
1252
+ * @lang en Optional default expansion state of an embedded preview, overridden by project-level defaultExpanded.
1253
+ */
425
1254
  defaultExpanded?: boolean;
1255
+ /**
1256
+ * @lang zh-CN 可选的预览代码语言标签。
1257
+ * @lang en Optional language label for the preview code.
1258
+ */
426
1259
  language?: string;
1260
+ /**
1261
+ * @lang zh-CN 可选的预览原始位置范围,用于内嵌预览标题与行号,同源查看页定位另取source.range。
1262
+ * @lang en Optional original-location range of the preview, used for embedded-preview captions and line numbers, while same-origin viewer positioning uses source.range.
1263
+ */
427
1264
  range?: {
1265
+ /**
1266
+ * @lang zh-CN 范围的一基起始位置,由上游定位信息提供。
1267
+ * @lang en One-based start position of the range, supplied by upstream location metadata.
1268
+ */
428
1269
  start: {
1270
+ /**
1271
+ * @lang zh-CN 上游提供的一基源码行号。
1272
+ * @lang en One-based source-line number supplied upstream.
1273
+ */
429
1274
  line: number;
1275
+ /**
1276
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
1277
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
1278
+ */
430
1279
  column?: number;
431
1280
  };
1281
+ /**
1282
+ * @lang zh-CN 可选的范围结束位置,其终点语义由对应上游契约规定。
1283
+ * @lang en Optional range end position, whose endpoint semantics are defined by the corresponding upstream contract.
1284
+ */
432
1285
  end?: {
1286
+ /**
1287
+ * @lang zh-CN 上游提供的一基源码行号。
1288
+ * @lang en One-based source-line number supplied upstream.
1289
+ */
433
1290
  line: number;
1291
+ /**
1292
+ * @lang zh-CN 上游提供的可选一基列号,列单位按对应来源契约解释。
1293
+ * @lang en Optional one-based column supplied upstream, with column units interpreted under the corresponding source contract.
1294
+ */
434
1295
  column?: number;
435
1296
  };
436
1297
  };
437
1298
  }
1299
+ /**
1300
+ * @lang zh-CN 渲染后的内存文件、诊断和manifest;宿主负责按许可写入与部署,调用前后不获得新的执行权限。
1301
+ * @lang en Rendered in-memory files, diagnostics and manifest; hosts own authorized writing/deployment and gain no new execution authority.
1302
+ */
438
1303
  export interface RenderHtmlResult {
1304
+ /**
1305
+ * @lang zh-CN 本次渲染返回的有序内存文件集合,宿主负责实际写入。
1306
+ * @lang en Ordered in-memory files returned by this render, with actual writes owned by the host.
1307
+ */
439
1308
  files: RenderedHtmlFile[];
1309
+ /**
1310
+ * @lang zh-CN 对应渲染入口返回的文档诊断,或合并后的项目输入与呈现资源诊断。
1311
+ * @lang en Document diagnostics returned by the document-rendering entry point, or combined project-input and presentation-asset diagnostics for project rendering.
1312
+ */
440
1313
  diagnostics: HiaDiagnostic[];
1314
+ /**
1315
+ * @lang zh-CN 登记本次输出文件元数据及可选项目引用的清单。
1316
+ * @lang en Manifest recording this render's output-file metadata and optional project references.
1317
+ */
441
1318
  manifest: RenderHtmlManifest;
442
1319
  }
443
1320
  /**
@@ -447,267 +1324,887 @@ export interface RenderHtmlResult {
447
1324
  * @returns <lang><zh-CN>同步完成或表示写入已完成的Promise。</zh-CN><en>Synchronous completion or a promise indicating the write completed.</en></lang>
448
1325
  */
449
1326
  export type RenderHtmlFileWriter = (file: RenderedHtmlFile) => void | Promise<void>;
450
- /** @lang zh-CN 逐文件渲染的无正文结果;索引/输入metadata仍随条目数增长。 @lang en Body-free result of per-file rendering; index/input metadata still grows with entry count. */
1327
+ /**
1328
+ * @lang zh-CN 逐文件渲染的无正文结果;索引/输入metadata仍随条目数增长。
1329
+ * @lang en Body-free result of per-file rendering; index/input metadata still grows with entry count.
1330
+ */
451
1331
  export interface RenderHtmlWriteResult {
452
- /** @lang zh-CN 已成功交给写入者的文件数,error诊断时为零。 @lang en Files successfully handed to the writer; zero for error diagnostics. */
1332
+ /**
1333
+ * @lang zh-CN 已成功交给写入者的文件数,error诊断时为零。
1334
+ * @lang en Files successfully handed to the writer; zero for error diagnostics.
1335
+ */
453
1336
  fileCount: number;
454
- /** @lang zh-CN 与普通API相同的诊断,不改变失败严重度。 @lang en Same diagnostics as the ordinary API, without changing failure severity. */
1337
+ /**
1338
+ * @lang zh-CN 与普通API相同的诊断,不改变失败严重度。
1339
+ * @lang en Same diagnostics as the ordinary API, without changing failure severity.
1340
+ */
455
1341
  diagnostics: HiaDiagnostic[];
456
- /** @lang zh-CN 仅文件清单/项目metadata,不含文件正文。 @lang en File inventory/project metadata only, without file bodies. */
1342
+ /**
1343
+ * @lang zh-CN 仅文件清单/项目metadata,不含文件正文。
1344
+ * @lang en File inventory/project metadata only, without file bodies.
1345
+ */
457
1346
  manifest: RenderHtmlManifest;
458
1347
  }
1348
+ /**
1349
+ * @lang zh-CN 本次输出文件及项目引用的body-free清单;只登记本次拥有的文件,不伪报外部共享资源或真实发布状态。
1350
+ * @lang en Body-free inventory of output files and project references, listing only files owned by this build rather than external shared assets or actual publication status.
1351
+ */
459
1352
  export interface RenderHtmlManifest {
1353
+ /**
1354
+ * @lang zh-CN 固定的HTML渲染输出清单版本0.1.0。
1355
+ * @lang en Fixed HTML render-output manifest version 0.1.0.
1356
+ */
460
1357
  schemaVersion: typeof HIA_RENDER_HTML_MANIFEST_SCHEMA_VERSION;
1358
+ /**
1359
+ * @lang zh-CN 固定的渲染器包标识@hia-doc/renderer-html。
1360
+ * @lang en Fixed renderer-package identifier @hia-doc/renderer-html.
1361
+ */
461
1362
  renderer: "@hia-doc/renderer-html";
1363
+ /**
1364
+ * @lang zh-CN 单文档身份或项目输出解析后的项目身份。
1365
+ * @lang en Document identity for a document render or resolved project identity for project output.
1366
+ */
462
1367
  documentId: string;
1368
+ /**
1369
+ * @lang zh-CN 本次渲染解析后的页面标题。
1370
+ * @lang en Resolved page title for this render.
1371
+ */
463
1372
  title: string;
1373
+ /**
1374
+ * @lang zh-CN 本次输出固定的index.html入口路径。
1375
+ * @lang en Fixed index.html entrypoint path for this output.
1376
+ */
464
1377
  entrypoint: string;
1378
+ /**
1379
+ * @lang zh-CN 本次选定的初始正文语言,独立于Portal界面语言。
1380
+ * @lang en Initial content locale selected for this render, independent of Portal UI locale.
1381
+ */
465
1382
  initialLocale: string;
1383
+ /**
1384
+ * @lang zh-CN 本次输出可切换的正文语言清单。
1385
+ * @lang en List of content locales available for switching in this output.
1386
+ */
466
1387
  locales: string[];
1388
+ /**
1389
+ * @lang zh-CN 本次拥有的文件路径、角色与媒体类型,不包含文件正文。
1390
+ * @lang en Paths, roles and media types of files owned by this render, without file contents.
1391
+ */
467
1392
  files: RenderHtmlManifestFile[];
1393
+ /**
1394
+ * @lang zh-CN 项目输出附加的项目元数据及导航、映射和投影引用。
1395
+ * @lang en Project metadata and navigation, mapping and projection references attached to project output.
1396
+ */
468
1397
  project?: {
1398
+ /**
1399
+ * @lang zh-CN 项目解析后的稳定标识,与清单documentId一致。
1400
+ * @lang en Resolved stable project identifier, matching the manifest documentId.
1401
+ */
469
1402
  id: string;
1403
+ /**
1404
+ * @lang zh-CN 调用方提供的公开项目名称。
1405
+ * @lang en Public project name supplied by the caller.
1406
+ */
470
1407
  name: string;
1408
+ /**
1409
+ * @lang zh-CN 本项目条目实际涉及的领域视图清单,包含汇总all视图。
1410
+ * @lang en Domain views represented by project entries, including the aggregate all view.
1411
+ */
471
1412
  views: RenderProjectView[];
1413
+ /**
1414
+ * @lang zh-CN 按领域视图累计的条目计数记录,all以条目总数初始化。
1415
+ * @lang en Entry-count records accumulated by domain view, with all initialized to the total entry count.
1416
+ */
472
1417
  entryCounts: Record<string, number>;
1418
+ /**
1419
+ * @lang zh-CN 可选的产品版本元数据,保持与文档路由独立。
1420
+ * @lang en Optional product-version metadata, independent of documentation routing.
1421
+ */
473
1422
  productVersion?: string;
1423
+ /**
1424
+ * @lang zh-CN 指向project-index.json的导航契约身份及条目计数引用。
1425
+ * @lang en Navigation contract identity and entry-count reference pointing to project-index.json.
1426
+ */
474
1427
  navigationIndex?: RenderProjectNavigationIndexRef;
1428
+ /**
1429
+ * @lang zh-CN 可选的项目级文档化配置规范引用集合。
1430
+ * @lang en Optional collection of project-level documentation-profile references.
1431
+ */
475
1432
  profiles?: RenderProjectProfileRef[];
1433
+ /**
1434
+ * @lang zh-CN 可选的项目文档源码映射引用及摘要集合。
1435
+ * @lang en Optional project documentation source-map references and summaries.
1436
+ */
476
1437
  docSourceMaps?: RenderProjectDocSourceMapRef[];
1438
+ /**
1439
+ * @lang zh-CN 可选的生成式文档绑定投影最小引用,完整投影位于项目索引。
1440
+ * @lang en Optional minimal reference to the generated-documentation-binding projection, whose full projection resides in the project index.
1441
+ */
477
1442
  generatedDocumentationBindingProjection?: RenderProjectGeneratedDocumentationBindingProjectionRef;
478
- /** @lang zh-CN `project-index.json` 内业务流程双投影的 body-free 引用。 @lang en Body-free reference to the business-flow dual projection in `project-index.json`. */
1443
+ /**
1444
+ * @lang zh-CN `project-index.json` 内业务流程双投影的 body-free 引用。
1445
+ * @lang en Body-free reference to the business-flow dual projection in `project-index.json`.
1446
+ */
479
1447
  businessFlowDocumentationProjection?: RenderProjectBusinessFlowDocumentationProjectionRef;
1448
+ /**
1449
+ * @lang zh-CN 可选的非空项目关系图计数引用,完整图位于项目索引。
1450
+ * @lang en Optional count reference to a non-empty project relation graph, whose full graph resides in the project index.
1451
+ */
480
1452
  relationGraph?: RenderProjectRelationGraphRef;
1453
+ /**
1454
+ * @lang zh-CN 显式启用时附加的已解析Portal信息架构契约。
1455
+ * @lang en Resolved Portal information-architecture contract attached when explicitly enabled.
1456
+ */
481
1457
  informationArchitecture?: DocumentationPortalInformationArchitectureContract;
482
- /** @lang zh-CN W-P123 metadata-only report 的 body-free 引用。 @lang en Body-free reference to the W-P123 metadata-only report. */
1458
+ /**
1459
+ * @lang zh-CN W-P123 metadata-only report 的 body-free 引用。
1460
+ * @lang en Body-free reference to the W-P123 metadata-only report.
1461
+ */
483
1462
  uiLocaleCompleteness?: RenderProjectUiLocaleCompletenessRef;
484
- /** @lang zh-CN 当前静态资源采用的 metadata-only theme reference。 @lang en Metadata-only theme reference used by the current static assets. */
1463
+ /**
1464
+ * @lang zh-CN 当前静态资源采用的 metadata-only theme reference。
1465
+ * @lang en Metadata-only theme reference used by the current static assets.
1466
+ */
485
1467
  theme?: DocumentationPortalThemeReference;
486
- /** @lang zh-CN neutral presentation profile 的最小引用。 @lang en Minimal reference to the neutral presentation profile. */
1468
+ /**
1469
+ * @lang zh-CN neutral presentation profile 的最小引用。
1470
+ * @lang en Minimal reference to the neutral presentation profile.
1471
+ */
487
1472
  presentationProfile?: RenderProjectPresentationProfileRef;
488
1473
  };
489
1474
  }
490
- /** @lang zh-CN manifest/index 共享的 UI locale completeness body-free 引用。 @lang en UI-locale-completeness body-free reference shared by the manifest and project index. */
1475
+ /**
1476
+ * @lang zh-CN manifest/index 共享的 UI locale completeness body-free 引用。
1477
+ * @lang en UI-locale-completeness body-free reference shared by the manifest and project index.
1478
+ */
491
1479
  export interface RenderProjectUiLocaleCompletenessRef {
1480
+ /**
1481
+ * @lang zh-CN 被引用界面语言完整性报告的契约名称。
1482
+ * @lang en Contract name of the referenced UI-locale completeness report.
1483
+ */
492
1484
  contract: DocumentationUiLocaleCompletenessReport["contract"];
1485
+ /**
1486
+ * @lang zh-CN 被引用报告的精确版本,当前Portal写者生成1.0.0。
1487
+ * @lang en Exact version of the referenced report, with the current Portal writer generating 1.0.0.
1488
+ */
493
1489
  contractVersion: DocumentationUiLocaleCompletenessReport["contractVersion"];
1490
+ /**
1491
+ * @lang zh-CN 报告展开后的界面面、执行模式与语言评估数量。
1492
+ * @lang en Number of expanded surface, execution-mode and locale evaluations in the report.
1493
+ */
494
1494
  evaluationCount: number;
1495
+ /**
1496
+ * @lang zh-CN 报告全部评估中精确语言命中的要求结果总数。
1497
+ * @lang en Total exact-locale requirement matches across all report evaluations.
1498
+ */
495
1499
  exactCount: number;
1500
+ /**
1501
+ * @lang zh-CN 固定的documentation-ui-locale-completeness.json报告路径。
1502
+ * @lang en Fixed documentation-ui-locale-completeness.json report path.
1503
+ */
496
1504
  path: typeof DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH;
1505
+ /**
1506
+ * @lang zh-CN 被评估Portal profile的稳定标识。
1507
+ * @lang en Stable identifier of the evaluated Portal profile.
1508
+ */
497
1509
  profileId: string;
1510
+ /**
1511
+ * @lang zh-CN 被引用报告的完整性状态,当前Portal写者要求complete。
1512
+ * @lang en Completeness state of the referenced report, required to be complete by the current Portal writer.
1513
+ */
498
1514
  status: DocumentationUiLocaleCompletenessReport["status"];
1515
+ /**
1516
+ * @lang zh-CN 本次Portal评估的界面面标识。
1517
+ * @lang en Surface identifier evaluated for this Portal render.
1518
+ */
499
1519
  surfaceId: string;
1520
+ /**
1521
+ * @lang zh-CN 报告覆盖的显式界面语言数量。
1522
+ * @lang en Number of explicit UI locales covered by the report.
1523
+ */
500
1524
  uiLocaleCount: number;
501
1525
  }
1526
+ /**
1527
+ * @lang zh-CN 输出清单中的相对路径、文件角色与MIME,不包含正文或文件系统写入权限。
1528
+ * @lang en Relative path, file role and MIME in an output inventory, without contents or filesystem-write authority.
1529
+ */
502
1530
  export interface RenderHtmlManifestFile {
1531
+ /**
1532
+ * @lang zh-CN 相对于本次输出根目录的文件路径。
1533
+ * @lang en File path relative to this render's output root.
1534
+ */
503
1535
  path: string;
1536
+ /**
1537
+ * @lang zh-CN 被登记文件的entry、asset或index角色。
1538
+ * @lang en Entry, asset or index role of the recorded file.
1539
+ */
504
1540
  role: RenderedHtmlFile["role"];
1541
+ /**
1542
+ * @lang zh-CN 被登记文件的媒体类型及适用字符集。
1543
+ * @lang en Media type and applicable character encoding of the recorded file.
1544
+ */
505
1545
  contentType: string;
506
1546
  }
507
1547
  /**
508
- * renderer 输出中项目导航索引的位置与兼容性标识。
509
- * Location and compatibility identity for the project navigation index emitted by the renderer.
1548
+ * @lang zh-CN renderer 输出中项目导航索引的位置与兼容性标识。
1549
+ * @lang en Location and compatibility identity for the project navigation index emitted by the renderer.
510
1550
  */
511
1551
  export interface RenderProjectNavigationIndexRef {
1552
+ /**
1553
+ * @lang zh-CN 固定的hia-project-navigation-index契约名称。
1554
+ * @lang en Fixed hia-project-navigation-index contract name.
1555
+ */
512
1556
  contract: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT;
513
- contractVersion: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION;
1557
+ /**
1558
+ * @lang zh-CN 固定的0.1.0-draft导航索引版本。
1559
+ * @lang en Fixed 0.1.0-draft navigation-index version.
1560
+ */
1561
+ contractVersion: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION | typeof HIA_PROJECT_SCOPED_NAVIGATION_INDEX_CONTRACT_VERSION;
1562
+ /**
1563
+ * @lang zh-CN 被引用导航索引中条目记录的数量。
1564
+ * @lang en Number of entry records in the referenced navigation index.
1565
+ */
514
1566
  entryCount: number;
1567
+ /**
1568
+ * @lang zh-CN 被引用项目导航索引的输出相对路径,当前写入project-index.json。
1569
+ * @lang en Output-relative path of the referenced project navigation index, currently written as project-index.json.
1570
+ */
515
1571
  path: string;
516
1572
  }
517
- /** @lang zh-CN manifest/index 指向 neutral presentation profile 的 body-free 引用。 @lang en Body-free manifest/index reference to the neutral presentation profile. */
1573
+ /**
1574
+ * @lang zh-CN manifest/index 指向 neutral presentation profile 的 body-free 引用。
1575
+ * @lang en Body-free manifest/index reference to the neutral presentation profile.
1576
+ */
518
1577
  export interface RenderProjectPresentationProfileRef {
1578
+ /**
1579
+ * @lang zh-CN 被引用中性呈现profile的契约名称。
1580
+ * @lang en Contract name of the referenced neutral presentation profile.
1581
+ */
519
1582
  contract: string;
1583
+ /**
1584
+ * @lang zh-CN 被引用呈现profile的精确版本标签。
1585
+ * @lang en Exact version label of the referenced presentation profile.
1586
+ */
520
1587
  contractVersion: string;
1588
+ /**
1589
+ * @lang zh-CN 固定的documentation-presentation-profile.json路径。
1590
+ * @lang en Fixed documentation-presentation-profile.json path.
1591
+ */
521
1592
  path: typeof PORTAL_PRESENTATION_PROFILE_PATH;
1593
+ /**
1594
+ * @lang zh-CN 被引用呈现profile的稳定标识。
1595
+ * @lang en Stable identifier of the referenced presentation profile.
1596
+ */
522
1597
  profileId: string;
1598
+ /**
1599
+ * @lang zh-CN 被引用profile的ready或refused状态,按资源级策略消费。
1600
+ * @lang en Ready or refused state of the referenced profile, consumed under per-asset policies.
1601
+ */
523
1602
  status: "ready" | "refused";
524
1603
  }
525
1604
  /**
526
- * renderer manifest 中 relation graph 的摘要引用,避免主 manifest 直接内嵌完整图。
527
- * Summary reference to the relation graph in the renderer manifest, avoiding full graph embedding in the main manifest.
1605
+ * @lang zh-CN renderer manifest 中 relation graph 的摘要引用,避免主 manifest 直接内嵌完整图。
1606
+ * @lang en Summary reference to the relation graph in the renderer manifest, avoiding full graph embedding in the main manifest.
528
1607
  */
529
1608
  export interface RenderProjectRelationGraphRef {
1609
+ /**
1610
+ * @lang zh-CN 被引用项目关系图的hia-project-relation-graph契约名称。
1611
+ * @lang en Hia-project-relation-graph contract name of the referenced project relation graph.
1612
+ */
530
1613
  contract: typeof HIA_PROJECT_RELATION_GRAPH_CONTRACT;
1614
+ /**
1615
+ * @lang zh-CN 被引用项目关系图的0.1.0-draft版本。
1616
+ * @lang en 0.1.0-draft version of the referenced project relation graph.
1617
+ */
531
1618
  contractVersion: typeof HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION;
1619
+ /**
1620
+ * @lang zh-CN 规范关系图中节点的数量。
1621
+ * @lang en Number of nodes in the normalized relation graph.
1622
+ */
532
1623
  nodeCount: number;
1624
+ /**
1625
+ * @lang zh-CN 规范关系图中有向关系的数量。
1626
+ * @lang en Number of directed relations in the normalized relation graph.
1627
+ */
533
1628
  relationCount: number;
1629
+ /**
1630
+ * @lang zh-CN 完整关系图所在的项目索引引用路径。
1631
+ * @lang en Project-index reference path containing the full relation graph.
1632
+ */
534
1633
  path: string;
535
1634
  }
536
1635
  /**
537
- * 中文:renderer manifest 中 generated binding relation 投影的最小引用。
538
- * English: Minimal generated-binding relation projection reference in the
539
- * renderer manifest.
1636
+ * @lang zh-CN renderer manifest 中 generated binding relation 投影的最小引用。
1637
+ * @lang en Minimal generated-binding relation projection reference in the renderer manifest.
540
1638
  */
541
1639
  export interface RenderProjectGeneratedDocumentationBindingProjectionRef {
1640
+ /**
1641
+ * @lang zh-CN 被引用生成式文档绑定投影摘要中的绑定数量。
1642
+ * @lang en Binding count from the referenced generated-documentation-binding projection summary.
1643
+ */
542
1644
  bindingCount: number;
1645
+ /**
1646
+ * @lang zh-CN 被引用绑定投影的契约名称。
1647
+ * @lang en Contract name of the referenced binding projection.
1648
+ */
543
1649
  contract: string;
1650
+ /**
1651
+ * @lang zh-CN 被引用绑定投影的精确版本标签。
1652
+ * @lang en Exact version label of the referenced binding projection.
1653
+ */
544
1654
  contractVersion: string;
1655
+ /**
1656
+ * @lang zh-CN 完整绑定投影所在的项目索引引用路径。
1657
+ * @lang en Project-index reference path containing the full binding projection.
1658
+ */
545
1659
  path: string;
1660
+ /**
1661
+ * @lang zh-CN 上游绑定投影提供的状态标签。
1662
+ * @lang en Status label supplied by the upstream binding projection.
1663
+ */
546
1664
  status: string;
1665
+ /**
1666
+ * @lang zh-CN 被引用绑定投影摘要中的目标数量。
1667
+ * @lang en Target count from the referenced binding projection summary.
1668
+ */
547
1669
  targetCount: number;
548
1670
  }
549
1671
  /**
550
- * @lang zh-CN
551
- * renderer manifest 对 public business-flow projection 的 body-free 引用与可审计计数;完整 payload 只存在于 project index。
1672
+ * @lang zh-CN renderer manifest 对 public business-flow projection 的 body-free 引用与可审计计数;完整 payload 只存在于 project index。
552
1673
  *
553
- * @lang en
554
- * Body-free renderer-manifest reference and auditable counts for a public business-flow projection; the full payload exists only in the project index.
1674
+ * @lang en Body-free renderer-manifest reference and auditable counts for a public business-flow projection; the full payload exists only in the project index.
555
1675
  */
556
1676
  export interface RenderProjectBusinessFlowDocumentationProjectionRef {
1677
+ /**
1678
+ * @lang zh-CN 固定的business-flow-documentation-projection契约名称。
1679
+ * @lang en Fixed business-flow-documentation-projection contract name.
1680
+ */
557
1681
  contract: "business-flow-documentation-projection";
1682
+ /**
1683
+ * @lang zh-CN 固定的0.1.0-draft业务流程投影版本。
1684
+ * @lang en Fixed 0.1.0-draft business-flow projection version.
1685
+ */
558
1686
  contractVersion: "0.1.0-draft";
1687
+ /**
1688
+ * @lang zh-CN 共享事实中的已选公开流程数量。
1689
+ * @lang en Number of selected public flows in shared facts.
1690
+ */
559
1691
  flowCount: number;
1692
+ /**
1693
+ * @lang zh-CN 全部人读线性视图的控制节点项总数。
1694
+ * @lang en Total control-node items across all human-linear views.
1695
+ */
560
1696
  humanItemCount: number;
1697
+ /**
1698
+ * @lang zh-CN 共享事实中控制、角色与工件节点的总数。
1699
+ * @lang en Total control, role and artifact nodes in shared facts.
1700
+ */
561
1701
  nodeCount: number;
1702
+ /**
1703
+ * @lang zh-CN 固定为project-index.json,完整业务流程投影位于该索引。
1704
+ * @lang en Fixed to project-index.json, where the full business-flow projection resides.
1705
+ */
562
1706
  path: "project-index.json";
1707
+ /**
1708
+ * @lang zh-CN 共享事实中控制、责任与数据关系的总数。
1709
+ * @lang en Total control, responsibility and data relations in shared facts.
1710
+ */
563
1711
  relationCount: number;
564
1712
  }
565
1713
  /**
566
- * 供 portal 使用的、无 HTML 表示细节的项目入口索引。
567
- * Project entry index without HTML presentation details, intended for portal consumption.
1714
+ * @lang zh-CN 供 portal 使用的、无 HTML 表示细节的项目入口索引。
1715
+ * @lang en Project entry index without HTML presentation details, intended for portal consumption.
568
1716
  */
569
1717
  export interface RenderProjectNavigationIndex {
1718
+ /**
1719
+ * @lang zh-CN 固定的hia-project-navigation-index契约名称。
1720
+ * @lang en Fixed hia-project-navigation-index contract name.
1721
+ */
570
1722
  contract: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT;
571
- contractVersion: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION;
1723
+ /**
1724
+ * @lang zh-CN 固定的0.1.0-draft导航索引版本。
1725
+ * @lang en Fixed 0.1.0-draft navigation-index version.
1726
+ */
1727
+ contractVersion: typeof HIA_PROJECT_NAVIGATION_INDEX_CONTRACT_VERSION | typeof HIA_PROJECT_SCOPED_NAVIGATION_INDEX_CONTRACT_VERSION;
1728
+ /**
1729
+ * @lang zh-CN 本次输出解析后的项目身份、标题、正文语言及领域统计。
1730
+ * @lang en Project identity, title, content locales and domain counts resolved for this output.
1731
+ */
572
1732
  project: {
1733
+ /**
1734
+ * @lang zh-CN 写入索引的本次初始正文语言,采用渲染选定语言。
1735
+ * @lang en Initial content locale recorded in the index, using the locale selected for this render.
1736
+ */
573
1737
  defaultLocale: string;
1738
+ /**
1739
+ * @lang zh-CN 按领域视图累计的条目计数记录,all以条目总数初始化。
1740
+ * @lang en Entry-count records accumulated by domain view, with all initialized to the total entry count.
1741
+ */
574
1742
  entryCounts: Record<string, number>;
1743
+ /**
1744
+ * @lang zh-CN 本次输出解析后的稳定项目标识。
1745
+ * @lang en Stable project identifier resolved for this output.
1746
+ */
575
1747
  id: string;
1748
+ /**
1749
+ * @lang zh-CN 初始选定、项目声明及条目字段推导语言合并去重后的正文语言清单。
1750
+ * @lang en Deduplicated content-locale list combining the initially selected locale, project declarations and locales inferred from entry fields.
1751
+ */
576
1752
  locales: string[];
1753
+ /**
1754
+ * @lang zh-CN 调用方提供的公开项目名称。
1755
+ * @lang en Public project name supplied by the caller.
1756
+ */
577
1757
  name: string;
1758
+ /**
1759
+ * @lang zh-CN 本次渲染解析后的项目页面标题。
1760
+ * @lang en Project-page title resolved for this render.
1761
+ */
578
1762
  title: string;
1763
+ /**
1764
+ * @lang zh-CN 实际条目涉及的领域视图清单,包含all汇总视图。
1765
+ * @lang en Domain views represented by actual entries, including the aggregate all view.
1766
+ */
579
1767
  views: RenderProjectView[];
1768
+ /**
1769
+ * @lang zh-CN 可选的产品版本元数据,保持与路由身份独立。
1770
+ * @lang en Optional product-version metadata, independent of routing identity.
1771
+ */
580
1772
  productVersion?: string;
581
1773
  };
1774
+ /**
1775
+ * @lang zh-CN 按稳定显示顺序排列的可导航文档条目元数据。
1776
+ * @lang en Navigable documentation-entry metadata arranged in stable display order.
1777
+ */
582
1778
  entries: RenderProjectNavigationEntry[];
1779
+ /**
1780
+ * @lang zh-CN 按条目类别、配置层和源码根生成的分组统计。
1781
+ * @lang en Group statistics generated by entry kind, profile layer and source root.
1782
+ */
583
1783
  groups: RenderProjectNavigationGroup[];
1784
+ /**
1785
+ * @lang zh-CN 按领域及已声明语义层级生成的完整导航树。
1786
+ * @lang en Complete navigation tree generated from domains and declared semantic hierarchy.
1787
+ */
584
1788
  navigationTree: RenderProjectNavigationTreeNode[];
1789
+ /**
1790
+ * @lang zh-CN 调用方项目级配置规范引用的排序副本,缺省为空数组。
1791
+ * @lang en Sorted copy of caller-supplied project-level profile references, defaulting to an empty array.
1792
+ */
585
1793
  profiles: RenderProjectProfileRef[];
1794
+ /**
1795
+ * @lang zh-CN 调用方项目级文档源码映射引用的排序副本,缺省为空数组。
1796
+ * @lang en Sorted copy of caller-supplied project-level documentation-map references, defaulting to an empty array.
1797
+ */
586
1798
  docSourceMaps: RenderProjectDocSourceMapRef[];
1799
+ /**
1800
+ * @lang zh-CN 可选的完整生成式文档绑定宿主投影。
1801
+ * @lang en Optional full generated-documentation-binding host projection.
1802
+ */
587
1803
  generatedDocumentationBindingProjection?: GeneratedDocumentationBindingHostProjection;
1804
+ /**
1805
+ * @lang zh-CN 可选的已通过摘要结构与计数校验的连续性元数据。
1806
+ * @lang en Optional continuity metadata that passed summary-shape and count validation.
1807
+ */
588
1808
  documentationContinuity?: RenderProjectDocumentationContinuitySummary;
1809
+ /**
1810
+ * @lang zh-CN 可选的负责人审阅准备度元数据,仅显式Portal信息架构消费。
1811
+ * @lang en Optional owner-review readiness metadata consumed only under explicit Portal information architecture.
1812
+ */
589
1813
  ownerAdoption?: RenderProjectOwnerAdoptionSummary;
590
- /** @lang zh-CN exact-valid public human/AI 双投影;可见表示等待独立设计基线。 @lang en Exact-valid public human/AI dual projection whose visible representation awaits an independent design baseline. */
1814
+ /**
1815
+ * @lang zh-CN exact-valid public human/AI 双投影;可见表示等待独立设计基线。
1816
+ * @lang en Exact-valid public human/AI dual projection whose visible representation awaits an independent design baseline.
1817
+ */
591
1818
  businessFlowDocumentationProjection?: BusinessFlowDocumentationProjection;
1819
+ /**
1820
+ * @lang zh-CN 可选的完整非空规范项目关系图。
1821
+ * @lang en Optional full non-empty normalized project relation graph.
1822
+ */
592
1823
  relationGraph?: RenderProjectRelationGraph;
1824
+ /**
1825
+ * @lang zh-CN 本次站点布局、源码策略及呈现/主题引用,含可选分片路径。
1826
+ * @lang en Site layout, source policy and presentation/theme references for this render, including optional shard paths.
1827
+ */
593
1828
  site?: {
1829
+ /**
1830
+ * @lang zh-CN 本次项目输出采用的split-site或single-page布局。
1831
+ * @lang en Split-site or single-page layout used for this project output.
1832
+ */
594
1833
  layout: RenderProjectSiteLayout;
1834
+ /**
1835
+ * @lang zh-CN split-site导航根分片的可选输出路径。
1836
+ * @lang en Optional output path of the split-site navigation root shard.
1837
+ */
595
1838
  navigationRootPath?: string;
1839
+ /**
1840
+ * @lang zh-CN split-site搜索索引的可选输出路径。
1841
+ * @lang en Optional output path of the split-site search index.
1842
+ */
596
1843
  searchIndexPath?: string;
1844
+ /**
1845
+ * @lang zh-CN split-site关系索引的可选输出路径。
1846
+ * @lang en Optional output path of the split-site relation index.
1847
+ */
597
1848
  relationIndexPath?: string;
1849
+ /**
1850
+ * @lang zh-CN 本次输出解析后的源码呈现策略,缺省为fetch。
1851
+ * @lang en Resolved source-presentation policy for this output, defaulting to fetch.
1852
+ */
598
1853
  sourcePresentation: RenderProjectSourcePresentation;
1854
+ /**
1855
+ * @lang zh-CN 当前中性呈现profile的最小契约引用。
1856
+ * @lang en Minimal contract reference to the current neutral presentation profile.
1857
+ */
599
1858
  presentationProfile: RenderProjectPresentationProfileRef;
1859
+ /**
1860
+ * @lang zh-CN 显式启用时记录的已解析Portal信息架构契约。
1861
+ * @lang en Resolved Portal information-architecture contract recorded when explicitly enabled.
1862
+ */
600
1863
  informationArchitecture?: DocumentationPortalInformationArchitectureContract;
601
- /** @lang zh-CN 当前 Portal surface 的 W-P123 report 引用。 @lang en W-P123 report reference for the current Portal surface. */
1864
+ /**
1865
+ * @lang zh-CN 当前 Portal surface 的 W-P123 report 引用。
1866
+ * @lang en W-P123 report reference for the current Portal surface.
1867
+ */
602
1868
  uiLocaleCompleteness?: RenderProjectUiLocaleCompletenessRef;
603
- /** @lang zh-CN Portal consumer 的 exact theme identity 与 system preference policy。 @lang en Exact theme identity and system-preference policy for portal consumers. */
1869
+ /**
1870
+ * @lang zh-CN Portal consumer 的 exact theme identity 与 system preference policy。
1871
+ * @lang en Exact theme identity and system-preference policy for portal consumers.
1872
+ */
604
1873
  theme: DocumentationPortalThemeReference;
605
1874
  };
606
1875
  }
1876
+ /**
1877
+ * @lang zh-CN 按类型、配置层或源码根聚合的导航分组闭集,不改变条目canonical身份。
1878
+ * @lang en Closed navigation grouping by kind, profile layer or source root, without changing canonical entry identities.
1879
+ */
607
1880
  export type RenderProjectNavigationGroupKind = "kind" | "profile-layer" | "source-root";
608
1881
  /**
609
- * 大型项目导航索引中的轻量分组统计,用于门户、侧栏和后续大项目导航策略。
610
- * Lightweight group statistics in the large-project navigation index for portals, sidebars, and future navigation strategies.
1882
+ * @lang zh-CN 大型项目导航索引中的轻量分组统计,用于门户、侧栏和后续大项目导航策略。
1883
+ * @lang en Lightweight group statistics in the large-project navigation index for portals, sidebars, and future navigation strategies.
611
1884
  */
612
1885
  export interface RenderProjectNavigationGroup {
1886
+ /**
1887
+ * @lang zh-CN 导航分组的稳定标识。
1888
+ * @lang en Stable identifier of the navigation group.
1889
+ */
613
1890
  id: string;
1891
+ /**
1892
+ * @lang zh-CN 按条目类别、配置层或源码根划分的分组类别。
1893
+ * @lang en Grouping kind based on entry kind, profile layer or source root.
1894
+ */
614
1895
  kind: RenderProjectNavigationGroupKind;
1896
+ /**
1897
+ * @lang zh-CN 导航分组的可公开显示标签。
1898
+ * @lang en Public display label of the navigation group.
1899
+ */
615
1900
  label: string;
1901
+ /**
1902
+ * @lang zh-CN 该分组关联的文档条目数量。
1903
+ * @lang en Number of documentation entries associated with the group.
1904
+ */
616
1905
  entryCount: number;
1906
+ /**
1907
+ * @lang zh-CN 该分组条目实际涉及的领域视图。
1908
+ * @lang en Domain views represented by entries in the group.
1909
+ */
617
1910
  views: RenderProjectView[];
618
1911
  }
1912
+ /**
1913
+ * @lang zh-CN 项目导航树节点类别闭集,仅表示已有层级,不额外推断语言命名空间或文件结构。
1914
+ * @lang en Closed project navigation-tree node kinds representing supplied hierarchy without inferring language namespaces or filesystem structure.
1915
+ */
619
1916
  export type RenderProjectNavigationTreeNodeKind = "view" | "assembly" | "surface" | "project" | "namespace" | "type" | "relation" | "source-root" | "source-file" | "entry" | DocumentationPortalSemanticPathKind;
620
1917
  /**
621
- * 项目级层级导航节点;用于把大型项目从平铺列表提升为可分域浏览的 API / 文件结构。
622
- * Project-level hierarchy node; it lifts large projects from a flat list into domain-aware API and file navigation.
1918
+ * @lang zh-CN 项目级层级导航节点;用于把大型项目从平铺列表提升为可分域浏览的 API / 文件结构。
1919
+ * @lang en Project-level hierarchy node; it lifts large projects from a flat list into domain-aware API and file navigation.
623
1920
  */
624
1921
  export interface RenderProjectNavigationTreeNode {
1922
+ /**
1923
+ * @lang zh-CN 层级导航节点的稳定引用标识。
1924
+ * @lang en Stable reference identifier of the hierarchy-navigation node.
1925
+ */
625
1926
  id: string;
1927
+ /**
1928
+ * @lang zh-CN 节点在领域、语义层级、源码或条目结构中的类别。
1929
+ * @lang en Node kind within the domain, semantic hierarchy, source or entry structure.
1930
+ */
626
1931
  kind: RenderProjectNavigationTreeNodeKind;
1932
+ /**
1933
+ * @lang zh-CN 节点的可公开显示标签。
1934
+ * @lang en Public display label of the node.
1935
+ */
627
1936
  label: string;
1937
+ /**
1938
+ * @lang zh-CN 节点关联的文档条目数量。
1939
+ * @lang en Number of documentation entries associated with the node.
1940
+ */
628
1941
  entryCount: number;
1942
+ /**
1943
+ * @lang zh-CN 节点覆盖的领域视图清单。
1944
+ * @lang en Domain views covered by the node.
1945
+ */
629
1946
  views: RenderProjectView[];
1947
+ /**
1948
+ * @lang zh-CN 完整树中可内嵌的子节点集合。
1949
+ * @lang en Child-node collection that may be embedded in the complete tree.
1950
+ */
630
1951
  children?: RenderProjectNavigationTreeNode[];
1952
+ /**
1953
+ * @lang zh-CN 延迟导航分片中指向子节点JSON的可选路径。
1954
+ * @lang en Optional path to child-node JSON in lazy navigation shards.
1955
+ */
631
1956
  childrenPath?: string;
1957
+ /**
1958
+ * @lang zh-CN 可选的规范条目片段路径,由条目标识派生。
1959
+ * @lang en Optional canonical entry-fragment path derived from the entry identifier.
1960
+ */
632
1961
  contentPath?: string;
1962
+ /**
1963
+ * @lang zh-CN 显式信息架构下的可选附加呈现路径,供实际加载使用。
1964
+ * @lang en Optional additive presentation path under explicit information architecture, used for actual loading.
1965
+ */
633
1966
  presentationPath?: string;
1967
+ /**
1968
+ * @lang zh-CN 可选的成员定位锚点,采用稳定条目标识。
1969
+ * @lang en Optional member-positioning anchor using the stable entry identifier.
1970
+ */
634
1971
  memberAnchor?: string;
1972
+ /**
1973
+ * @lang zh-CN 叶节点关联的可选稳定文档条目标识。
1974
+ * @lang en Optional stable documentation-entry identifier associated with a leaf node.
1975
+ */
635
1976
  entryId?: string;
1977
+ /**
1978
+ * @lang zh-CN 节点关联的可选源码路径元数据。
1979
+ * @lang en Optional source-path metadata associated with the node.
1980
+ */
636
1981
  sourcePath?: string;
1982
+ /**
1983
+ * @lang zh-CN 节点关联的可选上游规范符号标识。
1984
+ * @lang en Optional upstream canonical symbol identifier associated with the node.
1985
+ */
637
1986
  symbolId?: string;
638
1987
  }
639
1988
  /**
640
- * 单个可导航入口的稳定标识及其公开元数据;完整详情仍由统一项目页负责渲染。
641
- * Stable identity and public metadata for one navigable entry; the unified project page still renders full detail.
1989
+ * @lang zh-CN 单个可导航入口的稳定标识及其公开元数据;完整详情仍由统一项目页负责渲染。
1990
+ * @lang en Stable identity and public metadata for one navigable entry; the unified project page still renders full detail.
642
1991
  */
643
1992
  export interface RenderProjectNavigationEntry {
1993
+ /**
1994
+ * @lang zh-CN 新索引中显式保留的聚合作用域。
1995
+ * @lang en Explicit aggregation scope retained in the new index.
1996
+ */
1997
+ identityScope?: string;
1998
+ /**
1999
+ * @lang zh-CN 导航条目沿用的稳定文档条目标识。
2000
+ * @lang en Stable documentation-entry identifier preserved by the navigation entry.
2001
+ */
644
2002
  id: string;
2003
+ /**
2004
+ * @lang zh-CN 导航条目的公开显示名称。
2005
+ * @lang en Public display name of the navigation entry.
2006
+ */
645
2007
  name: string;
2008
+ /**
2009
+ * @lang zh-CN 上游领域生产方提供的条目语义类别。
2010
+ * @lang en Semantic entry kind supplied by the upstream domain producer.
2011
+ */
646
2012
  kind: string;
2013
+ /**
2014
+ * @lang zh-CN 导航条目所属的领域视图分组。
2015
+ * @lang en Domain-view grouping containing the navigation entry.
2016
+ */
647
2017
  view: RenderProjectView;
2018
+ /**
2019
+ * @lang zh-CN 可选的条目摘要文本。
2020
+ * @lang en Optional entry-summary text.
2021
+ */
648
2022
  summary?: string;
2023
+ /**
2024
+ * @lang zh-CN 可选的声明签名文本。
2025
+ * @lang en Optional declaration-signature text.
2026
+ */
649
2027
  signature?: string;
2028
+ /**
2029
+ * @lang zh-CN 可选的字段级中性多语言正文模型。
2030
+ * @lang en Optional neutral field-level multilingual content model.
2031
+ */
650
2032
  i18n?: HiaI18nModel;
2033
+ /**
2034
+ * @lang zh-CN 可选的条目文档化配置规范引用。
2035
+ * @lang en Optional documentation-profile reference for the entry.
2036
+ */
651
2037
  profile?: RenderProjectProfileRef;
2038
+ /**
2039
+ * @lang zh-CN 可选的来源输入工件元数据。
2040
+ * @lang en Optional metadata of the originating input artifact.
2041
+ */
652
2042
  input?: RenderProjectInputRef;
2043
+ /**
2044
+ * @lang zh-CN 可选的已应用源码策略的位置及资源元数据,预览正文从索引移除。
2045
+ * @lang en Optional source-policy-processed location and asset metadata, with preview bodies removed from the index.
2046
+ */
653
2047
  source?: Omit<RenderProjectSourceRef, "preview">;
654
- /** @lang zh-CN canonical navigation entry 上的 metadata-only source usability。 @lang en Metadata-only source usability on the canonical navigation entry. */
2048
+ /**
2049
+ * @lang zh-CN canonical navigation entry 上的 metadata-only source usability。
2050
+ * @lang en Metadata-only source usability on the canonical navigation entry.
2051
+ */
655
2052
  sourceUsability?: RenderProjectSourceUsabilityRef;
656
- /** @lang zh-CN 不含正文的 source-comment allowlist 摘要。 @lang en Body-free allowlisted source-comment summary. */
2053
+ /**
2054
+ * @lang zh-CN 不含正文的 source-comment allowlist 摘要。
2055
+ * @lang en Body-free allowlisted source-comment summary.
2056
+ */
657
2057
  sourceCommentProjection?: RenderProjectSourceCommentProjectionSummary;
2058
+ /**
2059
+ * @lang zh-CN 可选的上游规范符号标识。
2060
+ * @lang en Optional upstream canonical symbol identifier.
2061
+ */
658
2062
  symbolId?: string;
2063
+ /**
2064
+ * @lang zh-CN 可选的领域语义层级摘要。
2065
+ * @lang en Optional domain-semantic hierarchy summary.
2066
+ */
659
2067
  hierarchy?: RenderProjectEntryHierarchyRef;
2068
+ /**
2069
+ * @lang zh-CN 由条目ID派生的规范片段路径,split-site生成相应独立片段文件。
2070
+ * @lang en Canonical fragment path derived from the entry ID, with split-site generating the corresponding standalone fragment file.
2071
+ */
660
2072
  contentPath?: string;
661
- /** 实际 router fetch 位置;省略时与 canonical contentPath 相同。Actual router fetch location; omission means the canonical contentPath. */
2073
+ /**
2074
+ * @lang zh-CN 实际 router fetch 位置;省略时与 canonical contentPath 相同。
2075
+ * @lang en Actual router fetch location; omission means the canonical contentPath.
2076
+ */
662
2077
  presentationPath?: string;
663
- /** stable member/entry anchor。稳定 member/entry anchor。 */
2078
+ /**
2079
+ * @lang zh-CN 成员或条目的稳定锚点标识。
2080
+ * @lang en Stable anchor identifier for a member or entry.
2081
+ */
664
2082
  memberAnchor?: string;
665
- /** @lang zh-CN 不依赖 JavaScript 的独立多页阅读路径。 @lang en Standalone multi-page reading path that does not require JavaScript. */
2083
+ /**
2084
+ * @lang zh-CN 不依赖 JavaScript 的独立多页阅读路径。
2085
+ * @lang en Standalone multi-page reading path that does not require JavaScript.
2086
+ */
666
2087
  noScriptPagePath?: string;
667
- /** @lang zh-CN 按 UI locale 直接寻址的无脚本页面;与正文 locale 保持分层。 @lang en Direct no-script pages by UI locale, separate from content locale. */
2088
+ /**
2089
+ * @lang zh-CN 按 UI locale 直接寻址的无脚本页面;与正文 locale 保持分层。
2090
+ * @lang en Direct no-script pages by UI locale, separate from content locale.
2091
+ */
668
2092
  noScriptLocalePages?: Array<{
669
2093
  uiLocale: DocumentationPortalUiLocale;
670
2094
  path: string;
671
2095
  }>;
672
- /** @lang zh-CN neutral presentation profile 中的 topic identity。 @lang en Topic identity in the neutral presentation profile. */
2096
+ /**
2097
+ * @lang zh-CN neutral presentation profile 中的 topic identity。
2098
+ * @lang en Topic identity in the neutral presentation profile.
2099
+ */
673
2100
  presentationTopicId?: string;
674
- /** @lang zh-CN neutral presentation profile 中的 page identity。 @lang en Page identity in the neutral presentation profile. */
2101
+ /**
2102
+ * @lang zh-CN neutral presentation profile 中的 page identity。
2103
+ * @lang en Page identity in the neutral presentation profile.
2104
+ */
675
2105
  presentationPageId?: string;
676
- /** @lang zh-CN neutral presentation profile 中的 fragment identity。 @lang en Fragment identity in the neutral presentation profile. */
2106
+ /**
2107
+ * @lang zh-CN neutral presentation profile 中的 fragment identity。
2108
+ * @lang en Fragment identity in the neutral presentation profile.
2109
+ */
677
2110
  presentationFragmentId?: string;
2111
+ /**
2112
+ * @lang zh-CN 显式信息架构下的可选语义路径前缀,来自负责人审阅的清单输入。
2113
+ * @lang en Optional semantic-path prefix under explicit information architecture, taken from owner-reviewed manifest input.
2114
+ */
678
2115
  semanticPath?: DocumentationPortalSemanticPathSegment[];
2116
+ /**
2117
+ * @lang zh-CN 可选的条目与文档源码映射的轻量关联。
2118
+ * @lang en Optional lightweight linkage between the entry and its documentation source map.
2119
+ */
679
2120
  docSourceMap?: RenderProjectEntryDocSourceMapRef;
680
2121
  }
681
2122
  /**
682
- * @lang zh-CN
683
- * navigation/search consumer 可用的 metadata-only 摘要;不包含 projected text、source body 或 raw comment。
2123
+ * @lang zh-CN navigation/search consumer 可用的 metadata-only 摘要;不包含 projected text、source body 或 raw comment。
684
2124
  *
685
- * @lang en
686
- * Metadata-only summary for navigation consumers; it includes no projected text, source body, or raw comment.
2125
+ * @lang en Metadata-only summary for navigation consumers; it includes no projected text, source body, or raw comment.
687
2126
  */
688
2127
  export interface RenderProjectSourceCommentProjectionSummary {
2128
+ /**
2129
+ * @lang zh-CN 上游源码注释投影的契约名称。
2130
+ * @lang en Contract name of the upstream source-comment projection.
2131
+ */
689
2132
  contract: string;
2133
+ /**
2134
+ * @lang zh-CN 上游源码注释投影的精确版本标签。
2135
+ * @lang en Exact version label of the upstream source-comment projection.
2136
+ */
690
2137
  contractVersion: string;
2138
+ /**
2139
+ * @lang zh-CN 上游源码注释投影声明的默认语言。
2140
+ * @lang en Default locale declared by the upstream source-comment projection.
2141
+ */
691
2142
  defaultLocale: string;
2143
+ /**
2144
+ * @lang zh-CN 上游源码注释投影的条目总数。
2145
+ * @lang en Total number of entries in the upstream source-comment projection.
2146
+ */
692
2147
  entryCount: number;
2148
+ /**
2149
+ * @lang zh-CN 上游源码注释投影的稳定标识。
2150
+ * @lang en Stable identifier of the upstream source-comment projection.
2151
+ */
693
2152
  projectionId: string;
2153
+ /**
2154
+ * @lang zh-CN 调用方显式请求并与渲染选项匹配的注释语言。
2155
+ * @lang en Comment locale explicitly requested by the caller and matched against render options.
2156
+ */
694
2157
  requestedLocale: string;
2158
+ /**
2159
+ * @lang zh-CN 投影中resolution非missing的条目数量,包含回退解析结果。
2160
+ * @lang en Number of projection entries whose resolution is not missing, including fallback resolutions.
2161
+ */
695
2162
  resolvedCount: number;
2163
+ /**
2164
+ * @lang zh-CN 上游源码注释投影的ready或refused状态。
2165
+ * @lang en Ready or refused state of the upstream source-comment projection.
2166
+ */
696
2167
  status: "ready" | "refused";
2168
+ /**
2169
+ * @lang zh-CN 索引摘要关闭投影正文、原注释及源码正文的固定隐私标记。
2170
+ * @lang en Fixed privacy flags excluding projected text, raw comments and source bodies from the index summary.
2171
+ */
697
2172
  privacy: {
2173
+ /**
2174
+ * @lang zh-CN 固定为false,索引摘要不包含已投影注释正文。
2175
+ * @lang en Fixed to false, excluding projected comment text from the index summary.
2176
+ */
698
2177
  projectedCommentTextIncluded: false;
2178
+ /**
2179
+ * @lang zh-CN 固定为false,索引摘要不包含原始注释。
2180
+ * @lang en Fixed to false, excluding raw comments from the index summary.
2181
+ */
699
2182
  rawCommentIncluded: false;
2183
+ /**
2184
+ * @lang zh-CN 固定为false,索引摘要不包含源码正文。
2185
+ * @lang en Fixed to false, excluding source bodies from the index summary.
2186
+ */
700
2187
  sourceBodyIncluded: false;
2188
+ /**
2189
+ * @lang zh-CN 固定为none,索引摘要不携带sourcesContent。
2190
+ * @lang en Fixed to none, excluding sourcesContent from the index summary.
2191
+ */
701
2192
  sourcesContentPolicy: "none";
702
2193
  };
703
2194
  }
2195
+ /**
2196
+ * @lang zh-CN 把已结构化文档渲染为单页内存文件与manifest;默认包含主题资源,外部资源模式只返回引用,不写文件。
2197
+ * @lang en Renders a structured document into single-page in-memory files and a manifest; theme assets default on, while external-asset mode returns references without file writes.
2198
+ * @param document <lang><zh-CN>调用方已校验的HIA文档;此函数不是完整文档验证器。</zh-CN><en>Caller-validated HIA document; this function is not a complete document validator.</en></lang>
2199
+ * @param options <lang><zh-CN>标题、初始语言、主题及资产路由;项目策略仅按已声明兼容范围消费。</zh-CN><en>Title, initial locale, theme and asset routing; project policies apply only within their documented compatibility scope.</en></lang>
2200
+ * @returns <lang><zh-CN>有序内存文件、诊断和仅本次文件清单。</zh-CN><en>Ordered in-memory files, diagnostics and inventory of files owned by this build.</en></lang>
2201
+ * @throws {TypeError} <lang><zh-CN>显式主题颜色或资源路由非法时拒绝,不静默忽略。</zh-CN><en>Invalid explicit theme colors or asset routing are rejected rather than silently ignored.</en></lang>
2202
+ */
704
2203
  export declare function renderHtmlDocument(document: HiaDocument, options?: RenderHtmlOptions): RenderHtmlResult;
705
2204
  /**
706
- * @lang zh-CN
707
- * 把统一项目输入渲染为默认 split-site 或显式 single-page,并生成 exact presentation profile、内容寻址源码资源和 manifest linkage。
2205
+ * @lang zh-CN 把统一项目输入渲染为默认 split-site 或显式 single-page,并生成 exact presentation profile、内容寻址源码资源和 manifest linkage。
708
2206
  *
709
- * @lang en
710
- * Renders unified project input as the default split site or explicit single page, including an exact presentation profile, content-addressed source assets, and manifest linkage.
2207
+ * @lang en Renders unified project input as the default split site or explicit single page, including an exact presentation profile, content-addressed source assets, and manifest linkage.
711
2208
  *
712
2209
  * @param projectInput - 已结构化的项目、entry 与关系输入;renderer 不自行读取路径。Structured project, entry, and relation input; the renderer performs no path read.
713
2210
  * @param options - locale、IA、源码模式和 Portal theme 选择。Locale, IA, source-mode, and Portal-theme selections.