import type { Asset, ContentEntry } from "@cloudhal/core-contracts"; import { type BlockRegistry, createBlockRegistry } from "@cloudhal/core-ts/blocks"; import { type DirectiveToken, directiveExtension } from "@cloudhal/core-ts/body-blocks"; import { checkDirective, directiveProps } from "@cloudhal/core-ts/directives"; import { ASSET_HREF, assetUrl, mediaPath } from "@cloudhal/core-ts/media"; import { trimChar } from "@cloudhal/core-ts/names"; import { parseSurfaceFence } from "@cloudhal/core-ts/surfaces"; import { Marked } from "marked"; import { builtInBlockHtml, isBuiltInBlock, missingBlockHtml } from "./block-html.ts"; import { assetAlt, assetCaption, downloadMeta, imageAttributes, imgHtml, isAttachment, type MediaContext, } from "./media.ts"; import { safeHref, safeSrc } from "./safe-urls.ts"; import { sanitizeHtml } from "./sanitize.ts"; import { renderSurface, surfaceProblems } from "./surfaces.ts"; import { htmlText, leadingHeading, stripTags } from "./text-scan.ts"; export type { MediaContext } from "./media.ts"; export const escapeHtml = (s: string) => s.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """); export { safeHref, safeSrc }; /** The context of the markdown being rendered right now (`renderMarkdown` is synchronous). */ let current: MediaContext | undefined; /** Heading ids already given out in the document being rendered (nested renders share them). */ let headingIds: Map | undefined; /** While true (`renderInlineMarkdown`), images render as their text. */ let inlineOnly = false; /** The footnotes of the document being rendered: definitions by id (rendered), refs in order. */ let footnotes: { defs: Map; order: string[] } | undefined; const FN_REF = (id: string) => `\uE000fn:${id}\uE000`; const TURKISH: Record = { ı: "i", İ: "i", ş: "s", Ş: "s", ğ: "g", Ğ: "g" }; /** * Ids our own markup uses (comments, forms) or may use: a heading that would take one gets `h-` * in front, so content can never shadow an element Cloudhal's scripts look up by id. */ const RESERVED_ID = /^(?:comment|cloudhal|ch-)/; /** * A heading's anchor (RFC-0018 §3): ASCII slug of its text, unique in the document. Text without * Latin letters or digits falls back to `section`; repeats get `-2`, `-3`, …. */ export function headingSlug(text: string, taken?: Map): string { const dashed = text .replace(/[ıİşŞğĞ]/g, (c) => TURKISH[c] ?? c) .normalize("NFKD") .replace(/[̀-ͯ]/g, "") .toLowerCase() .replace(/ß/g, "ss") .replace(/[^a-z0-9]+/g, "-"); const base = trimChar(trimChar(dashed, "-").slice(0, 64), "-") || "section"; const slug = RESERVED_ID.test(base) || /^\d/.test(base) ? `h-${base}` : base; if (!taken) return slug; const seen = taken.get(slug) ?? 0; taken.set(slug, seen + 1); return seen === 0 ? slug : `${slug}-${seen + 1}`; } /** * `asset:` (exactly; RFC-0004 §7.6 rule 1) resolved against the render's assets. Anything else * under the scheme, an unknown id or no context resolves to nothing and renders like an unsafe URL. */ function resolveAsset(href: string): Asset | undefined { const m = ASSET_HREF.exec(href.trim()); if (!m) return undefined; const asset = current?.assets?.get(m[1] as string); if (!asset) current?.onMiss?.(m[1] as string); return asset; } function localeOf(): { locale: string; defaultLocale: string } { const defaultLocale = current?.defaultLocale ?? current?.locale ?? "en"; return { locale: current?.locale ?? defaultLocale, defaultLocale }; } /** A download link: the URL comes from validated parts only, the label is the markdown's (§7.6). */ function assetLink(asset: Asset, labelHtml: string, title?: string | null): string { const href = assetUrl(asset); const download = isAttachment(asset) ? " download" : ""; const link = `${labelHtml}`; return asset.kind === "document" || asset.kind === "data" || asset.kind === "other" ? `${link} ${downloadMeta(asset)}` : link; } function assetEmbed(asset: Asset, text: string, title?: string | null): string { const { locale, defaultLocale } = localeOf(); const alt = assetAlt(asset, text, locale, defaultLocale); const titleAttr = title ? ` title="${escapeHtml(title)}"` : ""; switch (asset.kind) { case "image": return imgHtml( imageAttributes( asset, { alt: text }, { locale, defaultLocale, transform: current?.transform ?? "none", ...(current?.budget ? { budget: current.budget } : {}), sizes: "(min-width: 48rem) 48rem, 100vw", ...(current?.preview ? { preview: true } : {}), }, ), titleAttr, ); case "video": case "audio": { const src = escapeHtml(assetUrl(asset)); const fallback = assetLink(asset, escapeHtml(alt || asset.slug)); return `<${asset.kind} controls preload="metadata" src="${src}"${alt ? ` aria-label="${escapeHtml(alt)}"` : ""}${titleAttr}>${fallback}`; } default: return assetLink(asset, escapeHtml(text || asset.slug), title); } } /** * Markdown is written by agents as well as people, so it is rendered as data, not markup: raw * HTML is escaped (no script/iframe/event handlers can reach the published site) and links and * images only keep safe URL schemes. `asset:` links and images resolve to the site's media. */ const md = new Marked({ gfm: true, async: false }); const builtInTypes = createBlockRegistry(); /** A theme's blocks in the body being rendered right now (`renderBodyParts`). */ let themed: { registry: BlockRegistry; names: ReadonlySet; slots: BlockSlot[] } | undefined; /** A body slot holding a ```surface fence (RFC-0020 §5); not a block type name (those are kebab). */ export const SURFACE_SLOT = "@surface"; /** Where a theme component goes in a body's HTML (`renderBodyParts`); escaped text never matches. */ const SLOT = (i: number) => ``; const SLOT_RE = //; md.use({ // Body directives (RFC-0015 §5): a built-in block renders like its component section; a // container's inner markdown goes through this same renderer. A type the theme renders with its // own component becomes a slot (`renderBodyParts`). Unknown types and props that do not fit // render nothing on the site and a labelled placeholder in previews. extensions: [ { // Footnotes (GFM): `[^id]` refers, `[^id]: text` defines (continued by indented lines). name: "footnoteDef", level: "block", start: (src: string) => src.match(/^\[\^[\w-]{1,40}\]:/m)?.index, tokenizer(src: string) { const m = /^\[\^([\w-]{1,40})\]:[ \t]+([^\n]*(?:\n(?: {2,}|\t)[^\n]*)*)(?:\n+|$)/.exec(src); if (!m) return undefined; const text = (m[2] ?? "").replace(/\n(?: {2,}|\t)/g, " "); return { type: "footnoteDef", raw: m[0], id: m[1], tokens: this.lexer.inlineTokens(text) }; }, renderer(token) { const t = token as unknown as { id: string; tokens: never[] }; if (footnotes && !footnotes.defs.has(t.id)) footnotes.defs.set(t.id, this.parser.parseInline(t.tokens)); return ""; }, }, { name: "footnoteRef", level: "inline", start: (src: string) => src.indexOf("[^"), tokenizer(src: string) { const m = /^\[\^([\w-]{1,40})\](?!:)/.exec(src); return m ? { type: "footnoteRef", raw: m[0], id: m[1] } : undefined; }, renderer(token) { const id = (token as unknown as { id: string }).id; if (!footnotes || inlineOnly) return escapeHtml(`[^${id}]`); if (!footnotes.order.includes(id)) footnotes.order.push(id); return FN_REF(id); }, }, { ...directiveExtension, renderer(token) { const { directive, tokens } = token as DirectiveToken; const registry = themed?.registry ?? current?.blocks ?? builtInTypes; const issues = checkDirective(registry, directive); const ctx = current; const valid = issues !== undefined && issues.length === 0; const props = directiveProps(registry.get(directive.name), directive.attrs); const contentHtml = directive.content !== undefined ? this.parser.parse(tokens) : undefined; if (valid && themed?.names.has(directive.name)) { themed.slots.push({ type: directive.name, props, ...(directive.content !== undefined ? { content: directive.content } : {}), ...(contentHtml !== undefined ? { contentHtml } : {}), }); return SLOT(themed.slots.length - 1); } const html = valid && isBuiltInBlock(directive.name) ? builtInBlockHtml(directive.name, props, { markdown: (source) => renderMarkdown(source, ctx), ...(contentHtml !== undefined ? { contentHtml } : {}), }) : ""; const attrs = `data-block-type="${escapeHtml(directive.name)}"`; if (html) return `
${html}
`; if (!ctx?.preview) return ""; return missingBlockHtml( "div", attrs, directive.name, issues === undefined ? "unknown block type" : valid ? "shown by the theme on the site" : "props do not fit the block type", ); }, }, ], renderer: { // Bodies carry no HTML (it is never trusted). A block of it (`
…
`, `
`) // loses its tags and keeps its words, so a reader never sees markup as text; inline `<…>` is // shown as typed (it is as often words in brackets as a tag). html({ text, block }) { if (inlineOnly || !block) return escapeHtml(text); const words = text .replace(/|$)/g, "") .replace(/<(script|style)\b[\s\S]*?(?:<\/\1\s*>|$)/gi, "") .replace(/<\/?[a-zA-Z][^>]*>/g, " ") .replace(/[ \t]+/g, " "); return words.trim() ? escapeHtml(words) : ""; }, // RFC-0020 §5: a ```surface fence is generative UI. With the theme's components it becomes a // slot `Body.astro` fills with `Surface.astro`; otherwise Cloudhal's own markup. Any other // fence is ordinary code. code({ text, lang }) { const info = /^surface(?:\s+(.*))?$/s.exec(lang ?? ""); if (!info) return false; const fence = parseSurfaceFence(info[1] ?? "", text.split("\n")); // A preview says why a block draws nothing; the published page stays silent about it. if (current?.preview) { const problems = surfaceProblems(fence.section, fence.issues, current.blocks); if (problems.length) return `

${ current.locale?.startsWith("tr") ? "Bu etkileşimli blok gösterilemiyor. Markdown modunda düzeltin:" : "This interactive block cannot be shown. Fix it in Markdown mode:" }

    ${problems .slice(0, 5) .map((p) => `
  • ${escapeHtml(p)}
  • `) .join("")}
`; } if (themed) { themed.slots.push({ type: SURFACE_SLOT, props: { surface: fence.section } }); return SLOT(themed.slots.length - 1); } return renderSurface(fence.section, { ...(current ? { media: current } : {}), ...(current?.preview ? { preview: true } : {}), }); }, // h2–h6 get ids for a table of contents and deep links; the h1 is the article's own title. heading({ tokens, depth }) { const inner = this.parser.parseInline(tokens); if (depth === 1) return `

${inner}

\n`; const id = headingSlug(htmlText(inner), headingIds); return `${inner}\n`; }, link({ href, title, tokens }) { const label = this.parser.parseInline(tokens); if (/^\s*asset:/i.test(href)) { const asset = resolveAsset(href); return asset ? assetLink(asset, label, title) : label; } const safe = safeHref(href); if (!safe) return label; return `${label}`; }, image({ href, title, text }) { if (inlineOnly) return escapeHtml(text); if (/^\s*asset:/i.test(href)) { const asset = resolveAsset(href); return asset ? assetEmbed(asset, text, title) : escapeHtml(text); } const safe = safeSrc(href); if (!safe) return escapeHtml(text); return `${escapeHtml(text)}`; }, }, }); /** * Renders markdown safely. With `ctx.assets`, `asset:` references become images, players and * download links (RFC-0004 §7.6); without it they degrade to their text, like any unsafe URL. */ export function renderMarkdown(source: string, ctx?: MediaContext): string { const previous = current; const outer = headingIds === undefined; current = ctx; if (outer) { headingIds = new Map(); footnotes = { defs: new Map(), order: [] }; } try { const html = md.parse(source) as string; return outer ? withFootnotes(html, ctx?.locale) : html; } finally { current = previous; if (outer) { headingIds = undefined; footnotes = undefined; } } } /** * Numbers the footnote references in order of first use and lists their definitions at the end, * each with a link back; a reference without a definition stays as written. */ function withFootnotes(html: string, locale = "en"): string { const fn = footnotes; if (!fn || !html.includes("\uE000fn:")) return html; const used = fn.order.filter((id) => fn.defs.has(id)); const tr = locale.startsWith("tr"); const out = html.replace(/\uE000fn:([\w-]{1,40})\uE000/g, (_, id: string) => { const n = used.indexOf(id) + 1; return n === 0 ? escapeHtml(`[^${id}]`) : `${n}`; }); if (used.length === 0) return out; const items = used .map( (id) => `
  • ${fn.defs.get(id)} ↩
  • `, ) .join(""); return `${out}

    ${tr ? "Dipnotlar" : "Footnotes"}

      ${items}
    `; } /** * Inline markdown, for short notes such as corrections (RFC-0019 §2): emphasis, code and safe * links; images become their text, and nothing block-level is produced. */ export function renderInlineMarkdown(source: string): string { const previous = inlineOnly; inlineOnly = true; try { return md.parseInline(source) as string; } finally { inlineOnly = previous; } } /** Markdown as plain text (meta descriptions): rendered safely, then tags dropped and entities decoded. */ export function markdownText(source: string): string { return htmlText(renderMarkdown(source)); } /** Inline markdown as plain text: inline tags go without leaving gaps ("**537**," → "537,"). */ export function inlineMarkdownText(source: string): string { return htmlText(stripTags(renderInlineMarkdown(source), "")); } export { htmlText }; /** * `markdown` bodies are rendered as data; `html` bodies go through the allowlist sanitizer * (RFC-0012): any writer can store them — agent keys over REST, `cloudhal push`, every role — so * pages, previews, feeds and static builds never publish them as stored. Neither resolves * `asset:` inside HTML (RFC-0004 §2.3). */ export function renderBody( body: { format: "markdown" | "html"; value: string }, ctx?: MediaContext, ): string { return body.format === "markdown" ? renderMarkdown(body.value, ctx) : sanitizeHtml(body.value); } /** A theme block in a body (RFC-0015 §5): its type, props and, for a container, its text. */ export interface BlockSlot { type: string; props: Record; /** A container's inner markdown. */ content?: string; /** The same, rendered by the safe renderer. */ contentHtml?: string; } /** A body as HTML runs and the theme blocks between them, in order. */ export type BodyPart = { html: string } | { slot: BlockSlot }; /** * A body for a theme that renders some block types with its own components (`Body.astro`): the * HTML is cut where each such block goes. `registry` holds the theme's types (validation); * `components` names the types the theme renders. Without any, it is `renderBody` in one part. */ export function renderBodyParts( body: { format: "markdown" | "html"; value: string }, ctx: MediaContext | undefined, blocks: { registry: BlockRegistry; components: ReadonlySet } | undefined, ): BodyPart[] { if ( body.format !== "markdown" || !blocks || (!body.value.includes("::") && !body.value.includes("surface")) ) return [{ html: renderBody(body, ctx) }]; const previous = themed; const slots: BlockSlot[] = []; themed = { registry: blocks.registry, names: blocks.components, slots }; let html: string; try { html = renderMarkdown(body.value, ctx); } finally { themed = previous; } const parts: BodyPart[] = []; const pieces = html.split(SLOT_RE); pieces.forEach((piece, i) => { if (i % 2 === 0) { if (piece) parts.push({ html: piece }); } else { const slot = slots[Number(piece)]; if (slot) parts.push({ slot }); } }); return parts; } /** * The cover image above the body: eager (it is the largest image above the fold), safe src only. * With its asset known, it gets the asset's size, alt fallback, placeholder, `srcset` when * transforming, and a caption with the credit (RFC-0004 §7.5, §7.7). */ function coverFigure(image: ContentEntry["coverImage"], ctx?: MediaContext): string { if (!image) return ""; const asset = image.assetId ? ctx?.assets?.get(image.assetId) : undefined; if (asset) { const defaultLocale = ctx?.defaultLocale ?? ctx?.locale ?? "en"; const locale = ctx?.locale ?? defaultLocale; const attrs = imageAttributes(asset, image, { locale, defaultLocale, transform: ctx?.transform ?? "none", ...(ctx?.budget ? { budget: ctx.budget } : {}), sizes: "(min-width: 48rem) 48rem, 100vw", priority: true, ...(ctx?.preview ? { preview: true } : {}), }); const caption = assetCaption(asset, locale, defaultLocale); return `
    ${imgHtml(attrs)}${caption ? `
    ${escapeHtml(caption)}
    ` : ""}
    `; } const src = safeSrc(image.src); if (!src) return ""; const size = image.width && image.height ? ` width="${image.width}" height="${image.height}"` : ""; return `
    ${escapeHtml(image.alt)}
    `; } /** An article's pieces: the body to render (a leading H1 repeating the title dropped) and the HTML around it. */ export function entryArticleParts( entry: Pick< ContentEntry, "id" | "title" | "summary" | "body" | "publishedAt" | "createdAt" | "coverImage" >, locale = "en", ctx?: MediaContext, ): { body: ContentEntry["body"]; header: string; cover: string; media: MediaContext } { let body = entry.body; if (body.format === "markdown") { const h1 = leadingHeading(body.value); if (h1 && h1.text.trim().toLowerCase() === entry.title.trim().toLowerCase()) body = { ...body, value: body.value.slice(h1.length) }; } const when = entry.publishedAt ?? undefined; const date = when ? `` : ""; const summary = entry.summary ? `

    ${escapeHtml(entry.summary)}

    ` : ""; const media: MediaContext = { locale, ...ctx }; return { body, header: `

    ${escapeHtml(entry.title)}

    ${summary}${date}
    `, cover: coverFigure(entry.coverImage, media), media, }; } /** * An article: a header (title, summary, publication date) followed by the body. A leading `# H1` * that repeats the title is dropped so authors may write it either way. Themes with their own * block components use `EntryArticle.astro`, which has the same markup. */ export function renderEntryArticle( entry: Pick< ContentEntry, "id" | "title" | "summary" | "body" | "publishedAt" | "createdAt" | "coverImage" >, locale = "en", ctx?: MediaContext, ): string { const { body, header, cover, media } = entryArticleParts(entry, locale, ctx); return `
    ${header}${cover}
    ${renderBody(body, media)}
    `; } /** The media path of an asset (re-exported for themes). */ export { mediaPath };