@publisle/adapter-core 0.2.0 → 0.2.2

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.
@@ -0,0 +1,1426 @@
1
+ import {
2
+ isInteractiveEnvelope,
3
+ locateDiagnostic,
4
+ type Block,
5
+ type BlockType,
6
+ type Diagnostic,
7
+ type InteractiveEnvelope,
8
+ type JsonValue,
9
+ type PreparedDocument,
10
+ type ReferenceTarget,
11
+ type InteractiveContent,
12
+ type ContractDependency,
13
+ richText,
14
+ createIslandInput,
15
+ } from "@publisle/schema";
16
+ let mathRenderer: typeof import("katex").default | undefined;
17
+ /** Install the shared renderer after a host explicitly loads math support. */
18
+ export function installMathRenderer(
19
+ renderer: typeof import("katex").default,
20
+ ): void {
21
+ mathRenderer = renderer;
22
+ }
23
+
24
+ import type {
25
+ AdapterCompilerOptions,
26
+ IslandRendererReference,
27
+ RenderNode,
28
+ RenderPlan,
29
+ } from "./types.ts";
30
+
31
+ type Inline = { type: string; [key: string]: unknown };
32
+ type Flow = { type: string; [key: string]: unknown };
33
+ const text = (value: string): RenderNode => ({ kind: "text", value });
34
+ const element = (
35
+ tag: string,
36
+ attributes: Record<string, string | number | boolean>,
37
+ children: readonly RenderNode[],
38
+ ): RenderNode => ({ kind: "element", tag, attributes, children });
39
+
40
+ /** Stable identity for a citation cluster, independent of object property order. */
41
+ export function citationKey(cluster: {
42
+ readonly items: readonly {
43
+ readonly id: string;
44
+ readonly locator?: string;
45
+ readonly label?: string;
46
+ readonly suppressAuthor?: boolean;
47
+ }[];
48
+ readonly prefix?: string;
49
+ readonly suffix?: string;
50
+ }): string {
51
+ return JSON.stringify([
52
+ cluster.items.map((item) => [
53
+ item.id,
54
+ item.locator ?? "",
55
+ item.label ?? "",
56
+ item.suppressAuthor ?? false,
57
+ ]),
58
+ cluster.prefix ?? "",
59
+ cluster.suffix ?? "",
60
+ ]);
61
+ }
62
+
63
+ function referenceText(target: ReferenceTarget): string {
64
+ if (target.kind === "heading") return target.title ?? target.label;
65
+ const name = target.kind.charAt(0).toUpperCase() + target.kind.slice(1);
66
+ return `${name} ${target.ordinal ?? ""}`.trim();
67
+ }
68
+
69
+ function renderMath(
70
+ value: string,
71
+ display: boolean,
72
+ diagnostics: Diagnostic[],
73
+ block: Block<BlockType, unknown>,
74
+ ): RenderNode[] {
75
+ try {
76
+ return [
77
+ {
78
+ kind: "raw",
79
+ value: mathRenderer!.renderToString(value, {
80
+ displayMode: display,
81
+ throwOnError: true,
82
+ trust: false,
83
+ strict: "warn",
84
+ maxExpand: 1000,
85
+ maxSize: 100,
86
+ output: "htmlAndMathml",
87
+ }),
88
+ },
89
+ ];
90
+ } catch (error) {
91
+ diagnostics.push({
92
+ level: "warning",
93
+ code: "invalid-math",
94
+ message:
95
+ error instanceof Error ? error.message : "Math rendering failed.",
96
+ blockId: block.id,
97
+ });
98
+ return [
99
+ element(display ? "pre" : "code", { class: "publisle-math-error" }, [
100
+ text(value),
101
+ ]),
102
+ ];
103
+ }
104
+ }
105
+
106
+ function safeUrl(url: string): string | undefined {
107
+ // Conservative superset of browser URL preprocessing, shared with Python.
108
+ // Browsers remove embedded TAB/LF/CR before identifying a scheme.
109
+ // eslint-disable-next-line no-control-regex -- deliberately remove URL control characters
110
+ const normalized = url.replace(/[\u0000-\u0020]/gu, "").toLowerCase();
111
+ return /^(?:javascript|vbscript|data):/u.test(normalized) ? undefined : url;
112
+ }
113
+
114
+ function safeEmbedUrl(url: string): string | undefined {
115
+ return /^https:\/\//iu.test(url.trim()) ? url : undefined;
116
+ }
117
+
118
+ const builtinEmbedProviders = {
119
+ youtube: (resourceId: string) => {
120
+ return /^[\w-]{6,20}$/u.test(resourceId)
121
+ ? {
122
+ src: `https://www.youtube-nocookie.com/embed/${resourceId}`,
123
+ allow: "accelerometer; autoplay; encrypted-media; picture-in-picture",
124
+ allowFullscreen: true,
125
+ }
126
+ : undefined;
127
+ },
128
+ vimeo: (resourceId: string) => {
129
+ return /^\d+$/u.test(resourceId)
130
+ ? {
131
+ src: `https://player.vimeo.com/video/${resourceId}`,
132
+ allow: "autoplay; fullscreen; picture-in-picture",
133
+ allowFullscreen: true,
134
+ }
135
+ : undefined;
136
+ },
137
+ } as const;
138
+
139
+ function inline(
140
+ nodes: readonly Inline[],
141
+ diagnostics: Diagnostic[],
142
+ block: Block<BlockType, unknown>,
143
+ references: readonly ReferenceTarget[] = [],
144
+ ): RenderNode[] {
145
+ return nodes.flatMap((node, index): RenderNode[] => {
146
+ switch (node.type) {
147
+ case "text": {
148
+ const value = String(node["value"] ?? "");
149
+ const direction = node["direction"];
150
+ if (direction === "ltr" || direction === "rtl" || direction === "auto")
151
+ return [element("span", { dir: direction }, [text(value)])];
152
+ return [text(value)];
153
+ }
154
+ case "emphasis":
155
+ return [
156
+ element(
157
+ "em",
158
+ {},
159
+ inline(
160
+ node["children"] as Inline[],
161
+ diagnostics,
162
+ block,
163
+ references,
164
+ ),
165
+ ),
166
+ ];
167
+ case "strong":
168
+ return [
169
+ element(
170
+ "strong",
171
+ {},
172
+ inline(
173
+ node["children"] as Inline[],
174
+ diagnostics,
175
+ block,
176
+ references,
177
+ ),
178
+ ),
179
+ ];
180
+ case "strikethrough":
181
+ return [
182
+ element(
183
+ "del",
184
+ {},
185
+ inline(
186
+ node["children"] as Inline[],
187
+ diagnostics,
188
+ block,
189
+ references,
190
+ ),
191
+ ),
192
+ ];
193
+ case "inlineCode":
194
+ return [element("code", {}, [text(String(node["value"] ?? ""))])];
195
+ case "inlineMath":
196
+ return renderMath(
197
+ String(node["value"] ?? ""),
198
+ false,
199
+ diagnostics,
200
+ block,
201
+ );
202
+ case "hardBreak":
203
+ return [element("br", {}, [])];
204
+ case "softBreak":
205
+ return [text("\n")];
206
+ case "footnoteReference": {
207
+ const localId = `footnote-${String(node["identifier"] ?? "")}`;
208
+ return [
209
+ element("sup", {}, [
210
+ element(
211
+ "a",
212
+ { href: `#${localId}`, "data-publisle-ref": localId },
213
+ [text(String(node["identifier"] ?? ""))],
214
+ ),
215
+ ]),
216
+ ];
217
+ }
218
+ case "citationReference": {
219
+ const items = Array.isArray(node["items"])
220
+ ? (node["items"] as Record<string, unknown>[])
221
+ : [];
222
+ const value = `${String(node["prefix"] ?? "")}${items
223
+ .map((item) => {
224
+ const id = String(item["id"] ?? "");
225
+ const locator =
226
+ typeof item["locator"] === "string" ? `, ${item["locator"]}` : "";
227
+ return `${id}${locator}`;
228
+ })
229
+ .join("; ")}${String(node["suffix"] ?? "")}`;
230
+ return [
231
+ element(
232
+ "span",
233
+ {
234
+ class: "publisle-citation",
235
+ "data-publisle-citation": JSON.stringify(items),
236
+ ...(node["prefix"]
237
+ ? { "data-publisle-citation-prefix": String(node["prefix"]) }
238
+ : {}),
239
+ ...(node["suffix"]
240
+ ? { "data-publisle-citation-suffix": String(node["suffix"]) }
241
+ : {}),
242
+ },
243
+ [text(`[${value}]`)],
244
+ ),
245
+ ];
246
+ }
247
+ case "crossReference": {
248
+ const target = String(node["target"] ?? "");
249
+ const resolved = references.find((entry) => entry.label === target);
250
+ const preceding = nodes
251
+ .slice(0, index)
252
+ .map(function plain(item): string {
253
+ return item.type === "text"
254
+ ? String(item["value"] ?? "")
255
+ : Array.isArray(item["children"])
256
+ ? (item["children"] as Inline[]).map(plain).join("")
257
+ : "";
258
+ })
259
+ .join("");
260
+ const kind = resolved?.kind;
261
+ const authoredKind =
262
+ kind &&
263
+ kind !== "heading" &&
264
+ new RegExp(`\\b${kind}\\s+$`, "iu").test(preceding);
265
+ const label = resolved
266
+ ? authoredKind
267
+ ? String(resolved.ordinal ?? resolved.label)
268
+ : referenceText(resolved)
269
+ : target;
270
+ const children = Array.isArray(node["children"])
271
+ ? inline(node["children"] as Inline[], diagnostics, block, references)
272
+ : [text(label)];
273
+ return [
274
+ element(
275
+ "a",
276
+ {
277
+ href: `#reference-${target}`,
278
+ "data-publisle-ref": `reference-${target}`,
279
+ ...(resolved ? {} : { "data-publisle-unresolved": true }),
280
+ },
281
+ children,
282
+ ),
283
+ ];
284
+ }
285
+ case "rawHtml":
286
+ return [
287
+ element("pre", { "data-publisle-raw-html": true }, [
288
+ text(String(node["value"] ?? "")),
289
+ ]),
290
+ ];
291
+ case "link": {
292
+ const url = safeUrl(String(node["url"] ?? ""));
293
+ if (!url)
294
+ diagnostics.push({
295
+ level: "warning",
296
+ code: "unsafe-url",
297
+ message: "An unsafe link URL was removed.",
298
+ blockId: block.id,
299
+ });
300
+ return [
301
+ element(
302
+ "a",
303
+ url ? { href: url } : {},
304
+ inline(
305
+ node["children"] as Inline[],
306
+ diagnostics,
307
+ block,
308
+ references,
309
+ ),
310
+ ),
311
+ ];
312
+ }
313
+ case "inlineImage": {
314
+ const url = safeUrl(String(node["url"] ?? ""));
315
+ if (!url)
316
+ diagnostics.push({
317
+ level: "warning",
318
+ code: "unsafe-url",
319
+ message: "An unsafe image URL was removed.",
320
+ blockId: block.id,
321
+ });
322
+ return [
323
+ element(
324
+ "img",
325
+ { ...(url ? { src: url } : {}), alt: String(node["alt"] ?? "") },
326
+ [],
327
+ ),
328
+ ];
329
+ }
330
+ default:
331
+ return [];
332
+ }
333
+ });
334
+ }
335
+
336
+ function flow(
337
+ nodes: readonly Flow[],
338
+ diagnostics: Diagnostic[],
339
+ block: Block<BlockType, unknown>,
340
+ references: readonly ReferenceTarget[] = [],
341
+ ): RenderNode[] {
342
+ return nodes.flatMap((node): RenderNode[] => {
343
+ switch (node.type) {
344
+ case "paragraph":
345
+ return [
346
+ element(
347
+ "p",
348
+ {},
349
+ inline(node["content"] as Inline[], diagnostics, block, references),
350
+ ),
351
+ ];
352
+ case "heading":
353
+ return [
354
+ element(
355
+ `h${Number(node["level"])}`,
356
+ {},
357
+ inline(node["content"] as Inline[], diagnostics, block, references),
358
+ ),
359
+ ];
360
+ case "quote":
361
+ return [
362
+ element(
363
+ "blockquote",
364
+ {},
365
+ flow(node["children"] as Flow[], diagnostics, block, references),
366
+ ),
367
+ ];
368
+ case "code":
369
+ return [
370
+ element("pre", {}, [
371
+ element(
372
+ "code",
373
+ typeof node["language"] === "string"
374
+ ? { class: `language-${node["language"]}` }
375
+ : {},
376
+ [text(String(node["value"] ?? ""))],
377
+ ),
378
+ ]),
379
+ ];
380
+ case "divider":
381
+ return [element("hr", {}, [])];
382
+ case "rawHtml":
383
+ return [
384
+ element("pre", { "data-publisle-raw-html": true }, [
385
+ text(String(node["value"] ?? "")),
386
+ ]),
387
+ ];
388
+ case "list": {
389
+ const ordered = node["ordered"] === true;
390
+ const items = node["items"] as {
391
+ checked?: boolean;
392
+ children: Flow[];
393
+ }[];
394
+ return [
395
+ element(
396
+ ordered ? "ol" : "ul",
397
+ ordered && typeof node["start"] === "number"
398
+ ? { start: node["start"] }
399
+ : {},
400
+ items.map((item) =>
401
+ element(
402
+ "li",
403
+ typeof item.checked === "boolean"
404
+ ? { class: "publisle-task-list-item" }
405
+ : {},
406
+ [
407
+ ...(typeof item.checked === "boolean"
408
+ ? [
409
+ element(
410
+ "input",
411
+ {
412
+ type: "checkbox",
413
+ disabled: true,
414
+ ...(item.checked ? { checked: true } : {}),
415
+ },
416
+ [],
417
+ ),
418
+ ]
419
+ : []),
420
+ ...flow(item.children, diagnostics, block, references),
421
+ ],
422
+ ),
423
+ ),
424
+ ),
425
+ ];
426
+ }
427
+ default:
428
+ return [];
429
+ }
430
+ });
431
+ }
432
+
433
+ function inlinePlain(nodes: readonly JsonValue[]): string {
434
+ return nodes
435
+ .map((node) => {
436
+ if (typeof node !== "object" || node === null || Array.isArray(node))
437
+ return "";
438
+ const record = node as Record<string, JsonValue>;
439
+ if (record["type"] === "text" && typeof record["value"] === "string")
440
+ return record["value"];
441
+ return Array.isArray(record["children"])
442
+ ? inlinePlain(record["children"])
443
+ : "";
444
+ })
445
+ .join("");
446
+ }
447
+
448
+ function envelopeProps(envelope: InteractiveEnvelope<JsonValue>): JsonValue {
449
+ const props: Record<string, JsonValue> = {
450
+ activation: envelope.activation,
451
+ payload: envelope.payload,
452
+ };
453
+ if (envelope.content !== undefined)
454
+ props["content"] = envelope.content as JsonValue;
455
+ if (envelope.fallback !== undefined) props["fallback"] = envelope.fallback;
456
+ if (envelope.initialState !== undefined)
457
+ props["initialState"] = envelope.initialState;
458
+ if (envelope.accessibility !== undefined)
459
+ props["accessibility"] = envelope.accessibility as JsonValue;
460
+ return props;
461
+ }
462
+
463
+ function nonempty(value: string | undefined, fallback: string): string {
464
+ return value !== undefined && value.length > 0 ? value : fallback;
465
+ }
466
+
467
+ function accessibleName(
468
+ envelope: InteractiveEnvelope<JsonValue>,
469
+ displayName?: string,
470
+ ): string {
471
+ const title = envelope.content?.title
472
+ ? inlinePlain(envelope.content.title).trim()
473
+ : "";
474
+ return nonempty(
475
+ envelope.accessibility?.label,
476
+ nonempty(title, displayName ?? "Interactive"),
477
+ );
478
+ }
479
+
480
+ function exploreLabel(
481
+ envelope: InteractiveEnvelope<JsonValue>,
482
+ displayName?: string,
483
+ ): string {
484
+ const title = envelope.content?.title
485
+ ? inlinePlain(envelope.content.title).trim()
486
+ : "";
487
+ const name = nonempty(
488
+ title,
489
+ envelope.accessibility?.label ?? displayName ?? "",
490
+ );
491
+ return name.length > 0 ? `Explore ${name}` : "Explore";
492
+ }
493
+
494
+ function contractProvenance(
495
+ type: BlockType,
496
+ pins: readonly ContractDependency[],
497
+ ): string | undefined {
498
+ const pin = pins.find((entry) => entry.type === type);
499
+ return pin ? `${pin.id} ${pin.digest}` : undefined;
500
+ }
501
+
502
+ function interactiveReference(
503
+ renderer: IslandRendererReference,
504
+ ): { module: string; exportName: string } | undefined {
505
+ if (renderer.interactive)
506
+ return {
507
+ module: renderer.interactive.module,
508
+ exportName: renderer.interactive.exportName ?? "default",
509
+ };
510
+ if (renderer.module)
511
+ return {
512
+ module: renderer.module,
513
+ exportName: renderer.exportName ?? "default",
514
+ };
515
+ return undefined;
516
+ }
517
+
518
+ function interactiveNodes(
519
+ block: Block<BlockType, unknown>,
520
+ envelope: InteractiveEnvelope<JsonValue>,
521
+ options: AdapterCompilerOptions,
522
+ diagnostics: Diagnostic[],
523
+ references: readonly ReferenceTarget[],
524
+ displayName?: string,
525
+ pins: readonly ContractDependency[] = [],
526
+ ): RenderNode[] {
527
+ const renderer = options.renderers?.[block.type];
528
+ const interactive = renderer ? interactiveReference(renderer) : undefined;
529
+ const staticRenderer = renderer?.static;
530
+ const description = envelope.content?.description;
531
+ const hasDescription = Array.isArray(description) && description.length > 0;
532
+ const fallbackContent = envelope.fallback ?? envelope.content?.fallback;
533
+ const hasFallback =
534
+ Array.isArray(fallbackContent) && fallbackContent.length > 0;
535
+ if (!staticRenderer && !hasFallback && !hasDescription) {
536
+ diagnostics.push({
537
+ level: "warning",
538
+ code: "missing-static-representation",
539
+ message: `Interactive block ${block.type} has no static representation.`,
540
+ blockId: block.id,
541
+ });
542
+ }
543
+ const explanation: RenderNode[] = [];
544
+ if (envelope.content?.title?.length) {
545
+ explanation.push(
546
+ element(
547
+ "p",
548
+ { class: "publisle-interactive-title" },
549
+ inline(
550
+ envelope.content.title as Inline[],
551
+ diagnostics,
552
+ block,
553
+ references,
554
+ ),
555
+ ),
556
+ );
557
+ }
558
+ if (hasDescription)
559
+ explanation.push(
560
+ ...flow(description as unknown as Flow[], diagnostics, block, references),
561
+ );
562
+ if (envelope.content?.instructions?.length)
563
+ explanation.push(
564
+ ...flow(
565
+ envelope.content.instructions as unknown as Flow[],
566
+ diagnostics,
567
+ block,
568
+ references,
569
+ ),
570
+ );
571
+ for (const key of ["purpose", "observations", "assumptions"] as const) {
572
+ const content = envelope.content?.[key];
573
+ if (content?.length)
574
+ explanation.push(
575
+ ...flow(content as Flow[], diagnostics, block, references),
576
+ );
577
+ }
578
+ for (const preset of envelope.content?.presets ?? []) {
579
+ if (preset.description?.length)
580
+ explanation.push(
581
+ ...flow(preset.description as Flow[], diagnostics, block, references),
582
+ );
583
+ }
584
+ const visualization: RenderNode[] = staticRenderer
585
+ ? [
586
+ {
587
+ kind: "component",
588
+ module: staticRenderer.module,
589
+ exportName: staticRenderer.exportName ?? "default",
590
+ blockId: block.id,
591
+ props: envelopeProps(envelope),
592
+ artifact: staticRenderer.lower
593
+ ? staticRenderer.lower(createIslandInput(block, envelope, pins))
594
+ : hasFallback
595
+ ? flow(
596
+ fallbackContent as unknown as Flow[],
597
+ diagnostics,
598
+ block,
599
+ references,
600
+ )
601
+ : [],
602
+ },
603
+ ]
604
+ : hasFallback
605
+ ? flow(
606
+ fallbackContent as unknown as Flow[],
607
+ diagnostics,
608
+ block,
609
+ references,
610
+ )
611
+ : [];
612
+ const provenance = contractProvenance(block.type, pins);
613
+ const region = (children: readonly RenderNode[]): RenderNode[] => [
614
+ element(
615
+ "section",
616
+ {
617
+ class: "publisle-interactive",
618
+ ...(provenance ? { "data-publisle-contract": provenance } : {}),
619
+ },
620
+ children,
621
+ ),
622
+ ];
623
+ if (!interactive) {
624
+ diagnostics.push({
625
+ level: "warning",
626
+ code: "missing-island-renderer",
627
+ message: `No island renderer is configured for ${block.type}.`,
628
+ blockId: block.id,
629
+ });
630
+ return region([...explanation, ...visualization]);
631
+ }
632
+ const fallback = [...visualization];
633
+ if (envelope.activation === "interaction") {
634
+ fallback.push(
635
+ element("button", { type: "button", "data-publisle-activate": "true" }, [
636
+ text(exploreLabel(envelope, displayName)),
637
+ ]),
638
+ );
639
+ }
640
+ return region([
641
+ ...explanation,
642
+ {
643
+ kind: "island",
644
+ blockId: block.id,
645
+ activation: envelope.activation,
646
+ label: accessibleName(envelope, displayName),
647
+ module: interactive.module,
648
+ exportName: interactive.exportName,
649
+ props: envelopeProps(envelope),
650
+ fallback,
651
+ ...(provenance ? { provenance } : {}),
652
+ },
653
+ ]);
654
+ }
655
+
656
+ function blockNodes(
657
+ block: Block<BlockType, unknown>,
658
+ options: AdapterCompilerOptions,
659
+ diagnostics: Diagnostic[],
660
+ references: readonly ReferenceTarget[],
661
+ displayName?: string,
662
+ pins: readonly ContractDependency[] = [],
663
+ ): RenderNode[] {
664
+ if (isInteractiveEnvelope(block.data))
665
+ return interactiveNodes(
666
+ block,
667
+ block.data,
668
+ options,
669
+ diagnostics,
670
+ references,
671
+ displayName,
672
+ pins,
673
+ );
674
+ const data = block.data as Record<string, unknown>;
675
+ const reference = references.find((entry) => entry.blockId === block.id);
676
+ switch (block.type) {
677
+ case "publisle:paragraph":
678
+ return [
679
+ element(
680
+ "p",
681
+ {},
682
+ inline(data["content"] as Inline[], diagnostics, block, references),
683
+ ),
684
+ ];
685
+ case "publisle:heading":
686
+ return [
687
+ element(
688
+ `h${Number(data["level"])}`,
689
+ {
690
+ "data-publisle-id": block.id,
691
+ ...(typeof data["label"] === "string"
692
+ ? { id: `reference-${data["label"]}` }
693
+ : {}),
694
+ },
695
+ inline(data["content"] as Inline[], diagnostics, block, references),
696
+ ),
697
+ ];
698
+ case "publisle:list":
699
+ return flow([{ type: "list", ...data }], diagnostics, block, references);
700
+ case "publisle:quote":
701
+ return [
702
+ element(
703
+ "blockquote",
704
+ {},
705
+ flow(data["children"] as Flow[], diagnostics, block, references),
706
+ ),
707
+ ];
708
+ case "publisle:code":
709
+ return flow([{ type: "code", ...data }], diagnostics, block, references);
710
+ case "publisle:math":
711
+ return [
712
+ element(
713
+ data["display"] === true ? "div" : "span",
714
+ {
715
+ class:
716
+ data["display"] === true && reference?.ordinal
717
+ ? "publisle-math publisle-math-numbered"
718
+ : "publisle-math",
719
+ ...(typeof data["label"] === "string"
720
+ ? { id: `reference-${data["label"]}` }
721
+ : {}),
722
+ },
723
+ [
724
+ ...renderMath(
725
+ String(data["value"] ?? ""),
726
+ data["display"] === true,
727
+ diagnostics,
728
+ block,
729
+ ),
730
+ ...(reference?.ordinal
731
+ ? [
732
+ element("span", { class: "publisle-equation-number" }, [
733
+ text(`(${reference.ordinal})`),
734
+ ]),
735
+ ]
736
+ : []),
737
+ ],
738
+ ),
739
+ ];
740
+ case "publisle:divider":
741
+ return [element("hr", {}, [])];
742
+ case "publisle:figure": {
743
+ const src = safeUrl(String(data["src"] ?? ""));
744
+ const original = data["original"] as Record<string, unknown> | undefined;
745
+ const originalSrc =
746
+ typeof original?.["src"] === "string"
747
+ ? safeUrl(original["src"])
748
+ : undefined;
749
+ if (!src)
750
+ diagnostics.push({
751
+ level: "warning",
752
+ code: "unsafe-url",
753
+ message: "An unsafe figure URL was removed.",
754
+ blockId: block.id,
755
+ });
756
+ // Alternative renditions keyed by variant name ("dark", …). The host's
757
+ // CSS decides which variant its active theme consumes; hosts without a
758
+ // mapping keep the base rendition.
759
+ const variants = Object.entries(
760
+ (data["variants"] ?? {}) as Record<string, unknown>,
761
+ ).flatMap(([name, value]): [string, string][] => {
762
+ if (typeof value !== "string") return [];
763
+ const variantSrc = safeUrl(value);
764
+ if (!variantSrc) {
765
+ diagnostics.push({
766
+ level: "warning",
767
+ code: "unsafe-url",
768
+ message: `An unsafe figure ${name} variant URL was removed.`,
769
+ blockId: block.id,
770
+ });
771
+ return [];
772
+ }
773
+ return [[name, variantSrc]];
774
+ });
775
+ const themed = src !== undefined && variants.length > 0;
776
+ return [
777
+ element(
778
+ "figure",
779
+ {
780
+ ...(typeof data["label"] === "string"
781
+ ? { id: `reference-${data["label"]}` }
782
+ : {}),
783
+ ...(themed ? { class: "publisle-figure-themed" } : {}),
784
+ },
785
+ [
786
+ element(
787
+ "img",
788
+ {
789
+ ...(src ? { src } : {}),
790
+ alt: String(data["alt"] ?? "Figure description missing."),
791
+ },
792
+ [],
793
+ ),
794
+ ...variants.map(([name, variantSrc]) =>
795
+ // The base image carries the description; renditions are decorative.
796
+ element(
797
+ "img",
798
+ {
799
+ src: variantSrc,
800
+ alt: "",
801
+ "data-publisle-variant": name,
802
+ "aria-hidden": "true",
803
+ },
804
+ [],
805
+ ),
806
+ ),
807
+ ...(data["alt"] === undefined
808
+ ? [
809
+ element("p", { class: "publisle-figure-missing-alt" }, [
810
+ text("Figure description missing."),
811
+ ]),
812
+ ]
813
+ : []),
814
+ ...(reference || Array.isArray(data["caption"])
815
+ ? [
816
+ element("figcaption", {}, [
817
+ ...(reference
818
+ ? [
819
+ element("span", { class: "publisle-figure-number" }, [
820
+ text(`${referenceText(reference)}. `),
821
+ ]),
822
+ ]
823
+ : []),
824
+ ...(Array.isArray(data["caption"])
825
+ ? flow(
826
+ data["caption"] as Flow[],
827
+ diagnostics,
828
+ block,
829
+ references,
830
+ )
831
+ : []),
832
+ ]),
833
+ ]
834
+ : []),
835
+ ...(Array.isArray(data["credit"])
836
+ ? [
837
+ element(
838
+ "small",
839
+ { class: "publisle-figure-credit" },
840
+ inline(
841
+ data["credit"] as Inline[],
842
+ diagnostics,
843
+ block,
844
+ references,
845
+ ),
846
+ ),
847
+ ]
848
+ : []),
849
+ ...(originalSrc
850
+ ? [
851
+ element(
852
+ "a",
853
+ {
854
+ class: "publisle-figure-original",
855
+ href: originalSrc,
856
+ download: String(original?.["filename"] ?? true),
857
+ },
858
+ [text("Download original")],
859
+ ),
860
+ ]
861
+ : []),
862
+ ],
863
+ ),
864
+ ];
865
+ }
866
+ case "publisle:table": {
867
+ const rows = data["rows"] as Inline[][][];
868
+ const align = data["align"] as ("left" | "right" | "center" | null)[];
869
+ return [
870
+ element(
871
+ "figure",
872
+ typeof data["label"] === "string"
873
+ ? { id: `reference-${data["label"]}` }
874
+ : {},
875
+ [
876
+ ...(reference || Array.isArray(data["caption"])
877
+ ? [
878
+ element("figcaption", {}, [
879
+ ...(reference
880
+ ? [
881
+ element("span", { class: "publisle-table-number" }, [
882
+ text(`${referenceText(reference)}. `),
883
+ ]),
884
+ ]
885
+ : []),
886
+ ...(Array.isArray(data["caption"])
887
+ ? flow(
888
+ data["caption"] as Flow[],
889
+ diagnostics,
890
+ block,
891
+ references,
892
+ )
893
+ : []),
894
+ ]),
895
+ ]
896
+ : []),
897
+ element("table", {}, [
898
+ element(
899
+ "tbody",
900
+ {},
901
+ rows.map((row, rowIndex) =>
902
+ element(
903
+ "tr",
904
+ {},
905
+ row.map((cell, cellIndex) =>
906
+ element(
907
+ (typeof data["headerRows"] === "number"
908
+ ? data["headerRows"]
909
+ : 1) > rowIndex
910
+ ? "th"
911
+ : "td",
912
+ {
913
+ ...((typeof data["headerRows"] === "number"
914
+ ? data["headerRows"]
915
+ : 1) > rowIndex
916
+ ? { scope: "col" }
917
+ : {}),
918
+ ...(align[cellIndex]
919
+ ? { class: `publisle-align-${align[cellIndex]}` }
920
+ : {}),
921
+ },
922
+ inline(cell, diagnostics, block, references),
923
+ ),
924
+ ),
925
+ ),
926
+ ),
927
+ ),
928
+ ]),
929
+ ],
930
+ ),
931
+ ];
932
+ }
933
+ case "publisle:callout":
934
+ return [
935
+ element(
936
+ "aside",
937
+ {
938
+ class: `publisle-callout publisle-callout-${String(data["variant"] ?? "note")}`,
939
+ },
940
+ [
941
+ ...(typeof data["title"] === "string"
942
+ ? [element("strong", {}, [text(data["title"])])]
943
+ : []),
944
+ ...flow(data["children"] as Flow[], diagnostics, block, references),
945
+ ],
946
+ ),
947
+ ];
948
+ case "publisle:footnote":
949
+ return [
950
+ element(
951
+ "aside",
952
+ { id: `footnote-${String(data["identifier"] ?? "")}` },
953
+ flow(data["children"] as Flow[], diagnostics, block, references),
954
+ ),
955
+ ];
956
+ case "publisle:embed": {
957
+ const providerName = String(data["provider"] ?? "");
958
+ const configuredProvider = options.embedProviders?.[providerName];
959
+ const builtinProvider =
960
+ builtinEmbedProviders[
961
+ providerName as keyof typeof builtinEmbedProviders
962
+ ];
963
+ const provider =
964
+ configuredProvider ??
965
+ (builtinProvider
966
+ ? (resourceId: string) => builtinProvider(resourceId)
967
+ : undefined);
968
+ const result = provider?.(String(data["resourceId"] ?? ""));
969
+ const embedSrc = result ? safeEmbedUrl(result.src) : undefined;
970
+ if (!result || !embedSrc) {
971
+ diagnostics.push({
972
+ level: "warning",
973
+ code: "missing-embed-provider",
974
+ message: `Embed provider ${providerName} is unavailable or rejected the resource ID.`,
975
+ blockId: block.id,
976
+ });
977
+ return Array.isArray(data["fallback"])
978
+ ? flow(data["fallback"] as Flow[], diagnostics, block, references)
979
+ : [
980
+ element(
981
+ "p",
982
+ { "data-publisle-embed-unavailable": providerName },
983
+ [text(String(data["title"] ?? "Embedded content"))],
984
+ ),
985
+ ];
986
+ }
987
+ const ratio = data["aspectRatio"] as Record<string, unknown>;
988
+ return [
989
+ element("figure", { class: "publisle-embed" }, [
990
+ element(
991
+ "iframe",
992
+ {
993
+ src: embedSrc,
994
+ title: String(data["title"] ?? ""),
995
+ loading: "lazy",
996
+ referrerpolicy: "strict-origin-when-cross-origin",
997
+ allow: result.allow ?? "fullscreen",
998
+ sandbox:
999
+ ("sandbox" in result ? result.sandbox : undefined) ??
1000
+ "allow-scripts allow-same-origin allow-presentation",
1001
+ ...(result.allowFullscreen ? { allowfullscreen: true } : {}),
1002
+ style: `aspect-ratio:${Number(ratio["width"] ?? 16)}/${Number(ratio["height"] ?? 9)}`,
1003
+ },
1004
+ [],
1005
+ ),
1006
+ ...(Array.isArray(data["caption"])
1007
+ ? [
1008
+ element(
1009
+ "figcaption",
1010
+ {},
1011
+ flow(
1012
+ data["caption"] as Flow[],
1013
+ diagnostics,
1014
+ block,
1015
+ references,
1016
+ ),
1017
+ ),
1018
+ ]
1019
+ : []),
1020
+ ]),
1021
+ ];
1022
+ }
1023
+ case "publisle:diagram": {
1024
+ const engine = String(data["engine"] ?? "");
1025
+ const renderer = options.diagramRenderers?.[engine];
1026
+ if (!renderer) {
1027
+ diagnostics.push({
1028
+ level: "warning",
1029
+ code: "missing-diagram-renderer",
1030
+ message: `No renderer is registered for diagram engine ${engine}.`,
1031
+ blockId: block.id,
1032
+ });
1033
+ const print = data["printFallback"] as
1034
+ Record<string, unknown> | undefined;
1035
+ const printSrc =
1036
+ typeof print?.["src"] === "string"
1037
+ ? safeUrl(print["src"])
1038
+ : undefined;
1039
+ const fallback = printSrc
1040
+ ? [
1041
+ element(
1042
+ "img",
1043
+ { src: printSrc, alt: String(data["alt"] ?? "") },
1044
+ [],
1045
+ ),
1046
+ ]
1047
+ : Array.isArray(data["fallback"])
1048
+ ? flow(data["fallback"] as Flow[], diagnostics, block, references)
1049
+ : [element("pre", {}, [text(String(data["source"] ?? ""))])];
1050
+ return [
1051
+ element(
1052
+ "figure",
1053
+ typeof data["label"] === "string"
1054
+ ? { id: `reference-${data["label"]}` }
1055
+ : {},
1056
+ [
1057
+ ...fallback,
1058
+ ...(reference || Array.isArray(data["caption"])
1059
+ ? [
1060
+ element("figcaption", {}, [
1061
+ ...(reference
1062
+ ? [
1063
+ element(
1064
+ "span",
1065
+ { class: "publisle-diagram-number" },
1066
+ [text(`${referenceText(reference)}. `)],
1067
+ ),
1068
+ ]
1069
+ : []),
1070
+ ...(Array.isArray(data["caption"])
1071
+ ? flow(
1072
+ data["caption"] as Flow[],
1073
+ diagnostics,
1074
+ block,
1075
+ references,
1076
+ )
1077
+ : []),
1078
+ ]),
1079
+ ]
1080
+ : []),
1081
+ ],
1082
+ ),
1083
+ ];
1084
+ }
1085
+ let result;
1086
+ try {
1087
+ result = renderer({
1088
+ engine,
1089
+ source: String(data["source"] ?? ""),
1090
+ alt: String(data["alt"] ?? ""),
1091
+ });
1092
+ } catch (error) {
1093
+ diagnostics.push({
1094
+ level: "warning",
1095
+ code: "diagram-render-failed",
1096
+ message:
1097
+ error instanceof Error
1098
+ ? error.message
1099
+ : `Rendering ${engine} failed.`,
1100
+ blockId: block.id,
1101
+ });
1102
+ return Array.isArray(data["fallback"])
1103
+ ? flow(data["fallback"] as Flow[], diagnostics, block, references)
1104
+ : [element("pre", {}, [text(String(data["source"] ?? ""))])];
1105
+ }
1106
+ const rendered: RenderNode[] = [...result.static];
1107
+ if (result.interactive)
1108
+ rendered.push({
1109
+ kind: "island",
1110
+ blockId: block.id,
1111
+ implementation: result.interactive.implementation,
1112
+ activation: result.interactive.activation ?? "visible",
1113
+ label: result.accessibleText ?? String(data["alt"] ?? "Diagram"),
1114
+ module: result.interactive.module,
1115
+ exportName: result.interactive.exportName ?? "default",
1116
+ props: result.interactive.props ?? {},
1117
+ fallback: result.static,
1118
+ });
1119
+ return [
1120
+ element(
1121
+ "figure",
1122
+ typeof data["label"] === "string"
1123
+ ? { id: `reference-${data["label"]}` }
1124
+ : {},
1125
+ [
1126
+ element("div", { class: "publisle-diagram-screen" }, rendered),
1127
+ ...(result.print
1128
+ ? [
1129
+ element(
1130
+ "div",
1131
+ { class: "publisle-diagram-print" },
1132
+ result.print,
1133
+ ),
1134
+ ]
1135
+ : []),
1136
+ ...(reference || Array.isArray(data["caption"])
1137
+ ? [
1138
+ element("figcaption", {}, [
1139
+ ...(reference
1140
+ ? [
1141
+ element(
1142
+ "span",
1143
+ { class: "publisle-diagram-number" },
1144
+ [text(`${referenceText(reference)}. `)],
1145
+ ),
1146
+ ]
1147
+ : []),
1148
+ ...(Array.isArray(data["caption"])
1149
+ ? flow(
1150
+ data["caption"] as Flow[],
1151
+ diagnostics,
1152
+ block,
1153
+ references,
1154
+ )
1155
+ : []),
1156
+ ]),
1157
+ ]
1158
+ : []),
1159
+ ],
1160
+ ),
1161
+ ];
1162
+ }
1163
+ case "publisle:bibliography": {
1164
+ const entries = Array.isArray(data["entries"]) ? data["entries"] : [];
1165
+ if (options.bibliography)
1166
+ return [
1167
+ element(
1168
+ "section",
1169
+ { class: "publisle-bibliography" },
1170
+ options.bibliography.map((entry) =>
1171
+ element("p", { "data-publisle-bibliography-id": entry.id }, [
1172
+ text(entry.text),
1173
+ ]),
1174
+ ),
1175
+ ),
1176
+ ];
1177
+ return [
1178
+ element(
1179
+ "section",
1180
+ { class: "publisle-bibliography" },
1181
+ entries.flatMap((entry) => {
1182
+ if (
1183
+ typeof entry !== "object" ||
1184
+ entry === null ||
1185
+ Array.isArray(entry)
1186
+ )
1187
+ return [];
1188
+ const record = entry as Record<string, unknown>;
1189
+ const authors = Array.isArray(record["authors"])
1190
+ ? record["authors"].filter(
1191
+ (author): author is string => typeof author === "string",
1192
+ )
1193
+ : [];
1194
+ const parts = [
1195
+ record["id"],
1196
+ ...authors,
1197
+ record["title"],
1198
+ record["raw"],
1199
+ ].filter((part): part is string => typeof part === "string");
1200
+ return [element("p", {}, [text(parts.join(" "))])];
1201
+ }),
1202
+ ),
1203
+ ];
1204
+ }
1205
+ case "publisle:raw-html":
1206
+ return options.rawHtml === "omit"
1207
+ ? []
1208
+ : options.rawHtml === "trusted" || typeof options.rawHtml === "function"
1209
+ ? [
1210
+ {
1211
+ kind: "raw",
1212
+ value:
1213
+ typeof options.rawHtml === "function"
1214
+ ? options.rawHtml(String(data["value"] ?? ""))
1215
+ : String(data["value"] ?? ""),
1216
+ },
1217
+ ]
1218
+ : [
1219
+ element("pre", { "data-publisle-raw-html": true }, [
1220
+ text(String(data["value"] ?? "")),
1221
+ ]),
1222
+ ];
1223
+ default:
1224
+ diagnostics.push({
1225
+ level: "warning",
1226
+ code: "missing-renderer",
1227
+ message: `No renderer is available for ${block.type}.`,
1228
+ blockId: block.id,
1229
+ });
1230
+ if ("readableContent" in block && block.readableContent) {
1231
+ const content = block.readableContent as InteractiveContent;
1232
+ const prose = content.fallback?.length
1233
+ ? [content.fallback]
1234
+ : [
1235
+ content.title,
1236
+ content.description,
1237
+ content.purpose,
1238
+ content.instructions,
1239
+ content.observations,
1240
+ content.assumptions,
1241
+ ...(content.presets?.map((preset) => preset.description) ?? []),
1242
+ ];
1243
+ return [
1244
+ element("section", { "data-publisle-unknown-block": block.type }, [
1245
+ ...(block.readable?.provenance.kind === "generated"
1246
+ ? [
1247
+ element("p", { "data-publisle-generated": true }, [
1248
+ text(
1249
+ `Generated by ${block.readable.provenance.generator} (${block.readable.provenance.version}); source: ${block.readable.provenance.source}.`,
1250
+ ),
1251
+ ]),
1252
+ ]
1253
+ : []),
1254
+ ...prose
1255
+ .filter((nodes) => nodes?.length)
1256
+ .map((nodes) => element("p", {}, [text(richText(nodes))])),
1257
+ ]),
1258
+ ];
1259
+ }
1260
+ return [
1261
+ element("div", { "data-publisle-unknown-block": block.type }, [
1262
+ text(`Unsupported block: ${block.type}`),
1263
+ ]),
1264
+ ];
1265
+ }
1266
+ }
1267
+
1268
+ export function createRenderPlan(
1269
+ document: PreparedDocument,
1270
+ options: AdapterCompilerOptions = {},
1271
+ ): RenderPlan {
1272
+ const diagnostics: Diagnostic[] = [];
1273
+ const nodes = applyFootnoteNumbers(
1274
+ document.blocks.flatMap((block) =>
1275
+ blockNodes(
1276
+ block,
1277
+ options,
1278
+ diagnostics,
1279
+ document.references.targets,
1280
+ document.islands.find((island) => island.blockId === block.id)
1281
+ ?.displayName,
1282
+ document.dependencies ?? [],
1283
+ ),
1284
+ ),
1285
+ collectFootnoteNumbers(document.blocks),
1286
+ );
1287
+ const base = {
1288
+ document,
1289
+ nodes: wrapInputs(resolveCitations(nodes, options.citations), document),
1290
+ diagnostics: diagnostics.map((diagnostic) =>
1291
+ locateDiagnostic(diagnostic, document.sourceMap),
1292
+ ),
1293
+ };
1294
+ return document.metadata === undefined
1295
+ ? base
1296
+ : { ...base, metadata: document.metadata };
1297
+ }
1298
+
1299
+ /** Footnote numbers by first-reference order, over the raw block payloads. */
1300
+ function collectFootnoteNumbers(
1301
+ blocks: readonly { readonly data: unknown }[],
1302
+ ): ReadonlyMap<string, number> {
1303
+ const numbers = new Map<string, number>();
1304
+ const visit = (value: unknown): void => {
1305
+ if (Array.isArray(value)) {
1306
+ value.forEach(visit);
1307
+ return;
1308
+ }
1309
+ if (!value || typeof value !== "object") return;
1310
+ const node = value as Record<string, unknown>;
1311
+ if (
1312
+ node["type"] === "footnoteReference" &&
1313
+ typeof node["identifier"] === "string" &&
1314
+ !numbers.has(node["identifier"])
1315
+ )
1316
+ numbers.set(node["identifier"], numbers.size + 1);
1317
+ for (const child of Object.values(node)) visit(child);
1318
+ };
1319
+ for (const block of blocks) visit(block.data);
1320
+ return numbers;
1321
+ }
1322
+
1323
+ /** Replace raw footnote labels with numbers on markers and definitions. */
1324
+ function applyFootnoteNumbers(
1325
+ nodes: readonly RenderNode[],
1326
+ numbers: ReadonlyMap<string, number>,
1327
+ ): RenderNode[] {
1328
+ return nodes.map((node) => {
1329
+ if (node.kind !== "element") return node;
1330
+ const reference = node.tag === "sup" ? node : undefined;
1331
+ const anchor = reference?.children.find(
1332
+ (child): child is Extract<RenderNode, { kind: "element" }> =>
1333
+ child.kind === "element" &&
1334
+ child.tag === "a" &&
1335
+ typeof child.attributes["data-publisle-ref"] === "string" &&
1336
+ child.attributes["data-publisle-ref"].startsWith("footnote-"),
1337
+ );
1338
+ if (anchor) {
1339
+ const identifier = String(anchor.attributes["data-publisle-ref"]).slice(
1340
+ "footnote-".length,
1341
+ );
1342
+ const number = numbers.get(identifier);
1343
+ return number === undefined
1344
+ ? node
1345
+ : {
1346
+ ...node,
1347
+ children: node.children.map((child) =>
1348
+ child === anchor
1349
+ ? { ...anchor, children: [text(String(number))] }
1350
+ : child,
1351
+ ),
1352
+ };
1353
+ }
1354
+ if (node.tag === "aside" && typeof node.attributes["id"] === "string") {
1355
+ const number = numbers.get(
1356
+ node.attributes["id"].slice("footnote-".length),
1357
+ );
1358
+ if (number !== undefined)
1359
+ return {
1360
+ ...node,
1361
+ children: [
1362
+ element("span", { class: "publisle-footnote-number" }, [
1363
+ text(`${String(number)}. `),
1364
+ ]),
1365
+ ...node.children,
1366
+ ],
1367
+ };
1368
+ }
1369
+ return { ...node, children: applyFootnoteNumbers(node.children, numbers) };
1370
+ });
1371
+ }
1372
+
1373
+ function resolveCitations(
1374
+ nodes: readonly RenderNode[],
1375
+ citations: AdapterCompilerOptions["citations"],
1376
+ ): RenderNode[] {
1377
+ if (!citations) return [...nodes];
1378
+ return nodes.map((node) => {
1379
+ if (node.kind === "island")
1380
+ return { ...node, fallback: resolveCitations(node.fallback, citations) };
1381
+ if (node.kind === "component" && node.artifact)
1382
+ return { ...node, artifact: resolveCitations(node.artifact, citations) };
1383
+ if (node.kind !== "element") return node;
1384
+ const raw = node.attributes["data-publisle-citation"];
1385
+ if (typeof raw === "string") {
1386
+ const key = citationKey({
1387
+ items: JSON.parse(raw) as Parameters<typeof citationKey>[0]["items"],
1388
+ prefix: String(node.attributes["data-publisle-citation-prefix"] ?? ""),
1389
+ suffix: String(node.attributes["data-publisle-citation-suffix"] ?? ""),
1390
+ });
1391
+ const value = citations[key];
1392
+ if (value !== undefined) return { ...node, children: [text(value)] };
1393
+ }
1394
+ return { ...node, children: resolveCitations(node.children, citations) };
1395
+ });
1396
+ }
1397
+
1398
+ function wrapInputs(
1399
+ nodes: readonly RenderNode[],
1400
+ document: PreparedDocument,
1401
+ ): RenderNode[] {
1402
+ return nodes.map((node) => {
1403
+ if (node.kind === "element")
1404
+ return { ...node, children: wrapInputs(node.children, document) };
1405
+ if (node.kind !== "island" && !(node.kind === "component" && node.blockId))
1406
+ return node;
1407
+ const block = document.blocks.find((entry) => entry.id === node.blockId);
1408
+ if (!block)
1409
+ throw new Error("Island input requires a corresponding prepared block.");
1410
+ const activation = node.kind === "island" ? node.activation : "visible";
1411
+ const envelope = isInteractiveEnvelope(node.props)
1412
+ ? node.props
1413
+ : { activation, payload: node.props };
1414
+ return {
1415
+ ...node,
1416
+ ...(node.kind === "island"
1417
+ ? { fallback: wrapInputs(node.fallback, document) }
1418
+ : {}),
1419
+ props: createIslandInput(
1420
+ block,
1421
+ envelope,
1422
+ document.dependencies,
1423
+ ) as unknown as JsonValue,
1424
+ };
1425
+ });
1426
+ }