1. 1//! Delivery boundary for declarative adaptive presentations.
2. 2//!
3. 3//! This adapter deliberately keeps the existing Markdown/document packet as
4. 4//! the lossless fallback. Rich data is an optional projection of an already
5. 5//! authorized structured result.
6. 6
7. 7use serde_json::Value;
8. 8use vak_presentation::{
9. 9 CompileInput, CompiledPresentation, LibraryScope, PresentationLibrary, Primitive, RenderNode,
10. 10};
11. 11
12. 12/// Lower a compiled presentation to conservative Markdown for surfaces that
13. 13/// cannot consume the native render tree. This is deliberately generic: it
14. 14/// understands the host primitive vocabulary, never semantic/domain names,
15. 15/// and returns the compiler's exact fallback when compilation degraded.
16. 16pub fn markdown(compiled: &CompiledPresentation) -> String {
17. 17 match compiled {
18. 18 CompiledPresentation::Fallback { text, .. } => text.clone(),
19. 19 CompiledPresentation::Rich(tree) => render_node(&tree.root, 0),
20. 20 }
21. 21}
22. 22
23. 23fn render_node(node: &RenderNode, depth: usize) -> String {
24. 24 let indent = " ".repeat(depth.min(8));
25. 25 let text = |key: &str| node.props.get(key).and_then(|v| v.as_str()).unwrap_or("");
26. 26 let entries = |key: &str| entry_lines(node, key);
27. 27 let mut out = String::new();
28. 28 match node.primitive {
29. 29 Primitive::Title => out.push_str(&format!("{}# {}\n", indent, text("text"))),
30. 30 Primitive::Section => out.push_str(&format!("{}## {}\n", indent, text("title"))),
31. 31 Primitive::Label | Primitive::Badge => {
32. 32 out.push_str(&format!("{}{}\n", indent, text("text")))
33. 33 }
34. 34 Primitive::Divider => out.push_str(&format!("{}---\n", indent)),
35. 35 Primitive::Quote | Primitive::Callout => {
36. 36 let value = text("text");
37. 37 if !value.is_empty() {
38. 38 out.push_str(&format!("> {}\n", value));
39. 39 }
40. 40 }
41. 41 Primitive::List | Primitive::Checklist | Primitive::Timeline | Primitive::Steps => {
42. 42 let value = text("text");
43. 43 if !value.is_empty() {
44. 44 out.push_str(&format!("{}- {}\n", indent, value));
45. 45 }
46. 46 }
47. 47 Primitive::KeyValue | Primitive::Progress => {
48. 48 let label = text("label");
49. 49 let value = text("value");
50. 50 if !label.is_empty() || !value.is_empty() {
51. 51 out.push_str(&format!("{}**{}:** {}\n", indent, label, value));
52. 52 }
53. 53 }
54. 54 Primitive::Metric => {
55. 55 let label = text("label");
56. 56 if let Some(value) = node.props.get("value") {
57. 57 let value = value
58. 58 .as_str()
59. 59 .map(str::to_owned)
60. 60 .unwrap_or_else(|| value.to_string());
61. 61 let unit = text("unit");
62. 62 out.push_str(&format!(
63. 63 "{}**{}:** {}{}\n",
64. 64 indent,
65. 65 label,
66. 66 value,
67. 67 if unit.is_empty() {
68. 68 String::new()
69. 69 } else {
70. 70 format!(" {unit}")
71. 71 }
72. 72 ));
73. 73 } else {
74. 74 if !label.is_empty() {
75. 75 out.push_str(&format!("{}**{}**\n", indent, label));
76. 76 }
77. 77 for (key, value) in &node.props {
78. 78 if matches!(key.as_str(), "label" | "title" | "semantic_type") {
79. 79 continue;
80. 80 }
81. 81 let value = value
82. 82 .as_str()
83. 83 .map(str::to_owned)
84. 84 .unwrap_or_else(|| value.to_string());
85. 85 out.push_str(&format!(
86. 86 "{}- {}: {}\n",
87. 87 indent,
88. 88 key.replace('_', " "),
89. 89 value
90. 90 ));
91. 91 }
92. 92 }
93. 93 }
94. 94 Primitive::Text
95. 95 | Primitive::RichText
96. 96 | Primitive::Group
97. 97 | Primitive::Stack
98. 98 | Primitive::Row
99. 99 | Primitive::Disclosure
100. 100 | Primitive::Comparison
101. 101 | Primitive::Table
102. 102 | Primitive::Chart
103. 103 | Primitive::DataGrid
104. 104 | Primitive::Image
105. 105 | Primitive::Audio
106. 106 | Primitive::Video
107. 107 | Primitive::File
108. 108 | Primitive::LinkPreview
109. 109 | Primitive::Gallery
110. 110 | Primitive::Diff
111. 111 | Primitive::TestMatrix
112. 112 | Primitive::Terminal
113. 113 | Primitive::Artifact
114. 114 | Primitive::CitationList
115. 115 | Primitive::Filter
116. 116 | Primitive::Sort
117. 117 | Primitive::Search
118. 118 | Primitive::Stepper
119. 119 | Primitive::Timer
120. 120 | Primitive::Loading
121. 121 | Primitive::Empty
122. 122 | Primitive::Partial
123. 123 | Primitive::Error
124. 124 | Primitive::Unavailable
125. 125 | Primitive::Stale
126. 126 | Primitive::Map
127. 127 | Primitive::Calendar
128. 128 | Primitive::Board
129. 129 | Primitive::Graph
130. 130 | Primitive::Entity
131. 131 | Primitive::Evidence
132. 132 | Primitive::Form
133. 133 | Primitive::Transaction
134. 134 | Primitive::Alert
135. 135 | Primitive::Conversation
136. 136 | Primitive::Simulation
137. 137 | Primitive::IngredientList
138. 138 | Primitive::StepList
139. 139 | Primitive::TakeawayList
140. 140 | Primitive::SourceList => {
141. 141 let value = text("text");
142. 142 if !value.is_empty() {
143. 143 out.push_str(&format!("{}{}\n", indent, value));
144. 144 }
145. 145 }
146. 146 Primitive::Recipe => {
147. 147 let title = text("title");
148. 148 if !title.is_empty() {
149. 149 out.push_str(&format!("{}## {}\n", indent, title));
150. 150 }
151. 151 for (label, key) in [("Serves", "servings"), ("Time", "total_time")] {
152. 152 let value = text(key);
153. 153 if !value.is_empty() {
154. 154 out.push_str(&format!("{}**{}:** {}\n", indent, label, value));
155. 155 }
156. 156 }
157. 157 let ingredients = entries("ingredients");
158. 158 if !ingredients.is_empty() {
159. 159 out.push_str(&format!("{}**Ingredients:**\n", indent));
160. 160 for ingredient in ingredients {
161. 161 out.push_str(&format!("{}- {}\n", indent, ingredient));
162. 162 }
163. 163 }
164. 164 let steps = entries("steps");
165. 165 if !steps.is_empty() {
166. 166 out.push_str(&format!("{}**Steps:**\n", indent));
167. 167 for (index, step) in steps.iter().enumerate() {
168. 168 out.push_str(&format!(
169. 169 "{}{}. {}\n",
170. 170 indent,
171. 171 index.saturating_add(1),
172. 172 step
173. 173 ));
174. 174 }
175. 175 }
176. 176 }
177. 177 Primitive::Research => {
178. 178 let title = text("title");
179. 179 if !title.is_empty() {
180. 180 out.push_str(&format!("{}## {}\n", indent, title));
181. 181 }
182. 182 let question = text("question");
183. 183 if !question.is_empty() {
184. 184 out.push_str(&format!("{}**Question:** {}\n", indent, question));
185. 185 }
186. 186 for (label, key) in [("Takeaways", "takeaways"), ("Sources", "sources")] {
187. 187 let values = entries(key);
188. 188 if !values.is_empty() {
189. 189 out.push_str(&format!("{}**{}:**\n", indent, label));
190. 190 for value in values {
191. 191 out.push_str(&format!("{}- {}\n", indent, value));
192. 192 }
193. 193 }
194. 194 }
195. 195 }
196. 196 Primitive::UiPreview => {
197. 197 // The previewed document is untrusted authored markup; plain-text
198. 198 // surfaces describe it rather than inlining it.
199. 199 let title = text("title");
200. 200 if !title.is_empty() {
201. 201 out.push_str(&format!("{}## {}\n", indent, title));
202. 202 }
203. 203 let caption = text("caption");
204. 204 if !caption.is_empty() {
205. 205 out.push_str(&format!("{}{}\n", indent, caption));
206. 206 }
207. 207 out.push_str(&format!(
208. 208 "{}_(interactive preview omitted on this surface)_\n",
209. 209 indent
210. 210 ));
211. 211 }
212. 212 }
213. 213 for child in &node.children {
214. 214 out.push_str(&render_node(child, depth.saturating_add(1)));
215. 215 }
216. 216 // Some valid packs bind the complete payload to a primitive whose text
217. 217 // lowering has no specialized shape (for example a universal entity or a
218. 218 // small comparison table). Never let a rich selection erase the result on
219. 219 // a constrained surface. Keep this structural and preserve every field.
220. 220 if out.trim().is_empty() {
221. 221 out.push_str(&render_bound_props(node, &indent));
222. 222 }
223. 223 out
224. 224}
225. 225
226. 226fn inline_value(value: &Value, depth: usize) -> String {
227. 227 if depth >= 8 {
228. 228 return value.to_string();
229. 229 }
230. 230 match value {
231. 231 Value::Null => "Unavailable".into(),
232. 232 Value::String(value) => value.clone(),
233. 233 Value::Number(value) => value.to_string(),
234. 234 Value::Bool(value) => {
235. 235 if *value {
236. 236 "Yes".into()
237. 237 } else {
238. 238 "No".into()
239. 239 }
240. 240 }
241. 241 Value::Array(items) => items
242. 242 .iter()
243. 243 .map(|item| inline_value(item, depth + 1))
244. 244 .collect::<Vec<_>>()
245. 245 .join("; "),
246. 246 Value::Object(fields) => fields
247. 247 .iter()
248. 248 .map(|(key, value)| {
249. 249 format!(
250. 250 "{}: {}",
251. 251 key.replace('_', " "),
252. 252 inline_value(value, depth + 1)
253. 253 )
254. 254 })
255. 255 .collect::<Vec<_>>()
256. 256 .join(" · "),
257. 257 }
258. 258}
259. 259
260. 260fn render_bound_props(node: &RenderNode, indent: &str) -> String {
261. 261 let mut out = String::new();
262. 262 for key in ["title", "summary"] {
263. 263 if let Some(value) = node.props.get(key).and_then(Value::as_str)
264. 264 && !value.is_empty()
265. 265 {
266. 266 if key == "title" {
267. 267 out.push_str(&format!("{indent}## {value}\n"));
268. 268 } else {
269. 269 out.push_str(&format!("{indent}{value}\n"));
270. 270 }
271. 271 }
272. 272 }
273. 273 for (key, value) in &node.props {
274. 274 if matches!(key.as_str(), "title" | "summary" | "semantic_type") {
275. 275 continue;
276. 276 }
277. 277 let label = key.replace('_', " ");
278. 278 if let Value::Array(items) = value {
279. 279 out.push_str(&format!("{indent}**{label}:**\n"));
280. 280 for item in items {
281. 281 out.push_str(&format!("{indent}- {}\n", inline_value(item, 0)));
282. 282 }
283. 283 } else {
284. 284 out.push_str(&format!(
285. 285 "{indent}**{label}:** {}\n",
286. 286 inline_value(value, 0)
287. 287 ));
288. 288 }
289. 289 }
290. 290 out
291. 291}
292. 292
293. 293/// Lower a list-shaped prop to plain lines. Stays structural: a string item is
294. 294/// used as-is, an object item is reduced through the same generic label/value
295. 295/// keys the rest of this lowering uses, never through domain field names.
296. 296fn entry_lines(node: &RenderNode, key: &str) -> Vec<String> {
297. 297 let Some(items) = node.props.get(key).and_then(|value| value.as_array()) else {
298. 298 return Vec::new();
299. 299 };
300. 300 items
301. 301 .iter()
302. 302 .filter_map(|item| match item {
303. 303 Value::String(value) => Some(value.clone()),
304. 304 Value::Object(fields) => {
305. 305 let pick = |name: &str| fields.get(name).and_then(|v| v.as_str()).unwrap_or("");
306. 306 let label = [pick("label"), pick("name"), pick("title")]
307. 307 .into_iter()
308. 308 .find(|value| !value.is_empty())
309. 309 .unwrap_or_default();
310. 310 let value = [pick("text"), pick("value"), pick("detail")]
311. 311 .into_iter()
312. 312 .find(|value| !value.is_empty())
313. 313 .unwrap_or_default();
314. 314 match (label.is_empty(), value.is_empty()) {
315. 315 (true, true) => None,
316. 316 (true, false) => Some(value.to_owned()),
317. 317 (false, true) => Some(label.to_owned()),
318. 318 (false, false) => Some(format!("{label}: {value}")),
319. 319 }
320. 320 }
321. 321 Value::Number(value) => Some(value.to_string()),
322. 322 _ => None,
323. 323 })
324. 324 .collect()
325. 325}
326. 326
327. 327pub fn project(
328. 328 library: &PresentationLibrary,
329. 329 semantic_type: &str,
330. 330 payload: Value,
331. 331 fallback_text: impl Into<String>,
332. 332 scope: LibraryScope,
333. 333 owner: &str,
334. 334) -> Option<CompiledPresentation> {
335. 335 let stored = library.select(semantic_type, scope, owner)?;
336. 336 Some(vak_presentation::compile(
337. 337 &stored.spec,
338. 338 &CompileInput {
339. 339 semantic_type: semantic_type.to_owned(),
340. 340 payload,
341. 341 fallback_text: fallback_text.into(),
342. 342 },
343. 343 ))
344. 344}
345. 345
346. 346pub fn project_preferred(
347. 347 library: &PresentationLibrary,
348. 348 semantic_type: &str,
349. 349 payload: Value,
350. 350 fallback_text: impl Into<String>,
351. 351 user_owner: &str,
352. 352 workspace_owner: &str,
353. 353) -> Option<CompiledPresentation> {
354. 354 let stored = library.select_preferred(semantic_type, user_owner, workspace_owner)?;
355. 355 Some(vak_presentation::compile(
356. 356 &stored.spec,
357. 357 &CompileInput {
358. 358 semantic_type: semantic_type.to_owned(),
359. 359 payload,
360. 360 fallback_text: fallback_text.into(),
361. 361 },
362. 362 ))
363. 363}
364. 364
365. 365#[cfg(test)]
366. 366#[allow(clippy::expect_used, clippy::unwrap_used)]
367. 367mod tests {
368. 368 use super::*;
369. 369 use vak_presentation::{
370. 370 LibraryScope, PresentationLibrary, PresentationOrigin, StoredPresentation, digest,
371. 371 };
372. 372
373. 373 fn library() -> PresentationLibrary {
374. 374 let spec: vak_presentation::PresentationSpec = serde_json::from_value(serde_json::json!({
375. 375 "schema_version": 1,
376. 376 "id": "demo.timeline",
377. 377 "revision": 1,
378. 378 "accepts": ["demo"],
379. 379 "root": { "primitive": "title", "props": { "text": { "kind": "binding", "path": "$.title" } }, "children": [] }
380. 380 }))
381. 381 .expect("spec");
382. 382 let mut library = PresentationLibrary::default();
383. 383 library
384. 384 .register(StoredPresentation {
385. 385 digest: digest(&spec).expect("digest"),
386. 386 spec,
387. 387 origin: PresentationOrigin {
388. 388 scope: LibraryScope::Workspace,
389. 389 owner: "workspace".into(),
390. 390 plugin_id: None,
391. 391 generation: None,
392. 392 },
393. 393 enabled: false,
394. 394 })
395. 395 .expect("register");
396. 396 library
397. 397 }
398. 398
399. 399 #[test]
400. 400 fn project_requires_explicit_activation_and_compiles_after_selection() {
401. 401 let mut library = library();
402. 402 assert!(
403. 403 project(
404. 404 &library,
405. 405 "demo",
406. 406 serde_json::json!({"title":"Preview"}),
407. 407 "Original",
408. 408 LibraryScope::Workspace,
409. 409 "workspace"
410. 410 )
411. 411 .is_none()
412. 412 );
413. 413 library
414. 414 .activate("demo.timeline", 1, LibraryScope::Workspace, "workspace")
415. 415 .expect("activate");
416. 416 let result = project(
417. 417 &library,
418. 418 "demo",
419. 419 serde_json::json!({"title":"Ready"}),
420. 420 "Original",
421. 421 LibraryScope::Workspace,
422. 422 "workspace",
423. 423 )
424. 424 .expect("projection");
425. 425 assert!(matches!(result, CompiledPresentation::Rich(_)));
426. 426 }
427. 427
428. 428 #[test]
429. 429 fn markdown_lowering_is_generic_and_preserves_compiler_fallback() {
430. 430 let mut library = library();
431. 431 assert_eq!(
432. 432 markdown(&CompiledPresentation::Fallback {
433. 433 text: "Original answer".into(),
434. 434 reason: "invalid payload".into(),
435. 435 }),
436. 436 "Original answer"
437. 437 );
438. 438 library
439. 439 .activate("demo.timeline", 1, LibraryScope::Workspace, "workspace")
440. 440 .expect("activate");
441. 441 let compiled = project(
442. 442 &library,
443. 443 "demo",
444. 444 serde_json::json!({"title":"Ready"}),
445. 445 "Original",
446. 446 LibraryScope::Workspace,
447. 447 "workspace",
448. 448 )
449. 449 .expect("projection");
450. 450 assert!(markdown(&compiled).contains("Ready"));
451. 451 }
452. 452}
453. 453