@druck-editorial/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Iagovdik <artyom.yagovdik@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @druck-editorial/engine
+
+Editorial rendering engine. Takes structured `ArticleData` JSON and returns magazine-quality HTML strings.
+
+## Install
+
+```bash
+pnpm add @druck-editorial/engine
+```
+
+## API
+
+```ts
+import { renderArticle, renderCard, buildFrontPage, renderFrontPage } from '@druck-editorial/engine';
+import type { ArticleData, RenderOptions } from '@druck-editorial/engine';
+```
+
+### renderArticle
+
+Renders a full article page shell with hero, chapters, key points, and related articles.
+
+```ts
+const html = renderArticle(
+  {
+    title: 'The infrastructure gap',
+    subtitle: 'Why deployment costs diverged from benchmark results in 2025.',
+    metaDescription: 'A look at the growing gap between frontier model benchmarks and production deployment.',
+    slug: 'infrastructure-gap-2025',
+    format: 'feature',
+    category: 'ai',
+    publishedAt: '2025-11-14T09:00:00Z',
+    heroImage: 'https://example.com/hero.webp',
+    chapters: [
+      {
+        title: 'The economics',
+        bodyHtml: '<p>Running GPT-4-class inference at scale costs between $12-30 per million tokens.</p>',
+      },
+    ],
+  },
+  { lang: 'en', theme: 'light' }
+);
+```
+
+`format` is `'feature' | 'quick_take' | 'wire'`. Feature articles use the full chapter + key-points layout. Wire uses a single `bodyHtml` block.
+
+### renderCard
+
+Renders a card tile for use in a feed grid.
+
+```ts
+const cardHtml = renderCard(articleData, options);
+```
+
+### buildFrontPage + renderFrontPage
+
+`buildFrontPage` groups an array of `ArticleData` into layout rows (`hero`, `feature`, `triple`, `brief`). `renderFrontPage` turns those rows into HTML.
+
+```ts
+const rows = buildFrontPage(items);
+const html = renderFrontPage(rows, { lang: 'de' });
+```
+
+## RenderOptions
+
+| Field | Type | Description |
+|---|---|---|
+| `lang` | `string` | Sets `lang` attribute on the article shell. |
+| `theme` | `'light' \| 'dark'` | Sets `data-theme` on the shell. |
+| `accentColor` | `string` | CSS value applied to `--accent`. |
+| `siteName` | `string` | Site name shown in byline and colophon. |
+| `siteUrl` | `string` | Used for share and canonical links. |
+| `canonicalUrl` | `string` | Override for the canonical URL. |
+| `ogImageUrl` | `string` | Override for the OG image meta tag. |

package/dist/format.d.ts

@@ -0,0 +1,5 @@
+declare function escapeHtml(s: string): string;
+declare function sanitizeInline(html: string): string;
+declare function transformInlineBlocks(bodyHtml: string): string;
+declare function safeUrl(url: string): string;
+export { escapeHtml, sanitizeInline, transformInlineBlocks, safeUrl };

package/dist/format.js

@@ -0,0 +1,115 @@
+const INLINE_ALLOWED_TAGS = new Set(['strong', 'em', 'b', 'i', 'span', 'a']);
+const INLINE_ALLOWED_ATTRS = {
+    a: new Set(['href']),
+    span: new Set(['class']),
+    strong: new Set(['class']),
+    em: new Set(['class']),
+};
+const SAFE_HREF_RE = /^(?:https?:|mailto:|\/|#)/i;
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function sanitizeInline(html) {
+    let out = '';
+    let i = 0;
+    while (i < html.length) {
+        if (html[i] === '<') {
+            const closeMatch = html.slice(i).match(/^<\/(\w+)\s*>/);
+            if (closeMatch) {
+                const tag = closeMatch[1].toLowerCase();
+                if (INLINE_ALLOWED_TAGS.has(tag))
+                    out += `</${tag}>`;
+                i += closeMatch[0].length;
+                continue;
+            }
+            const openMatch = html.slice(i).match(/^<(\w+)([^>]*?)>/);
+            if (openMatch) {
+                const tag = openMatch[1].toLowerCase();
+                if (INLINE_ALLOWED_TAGS.has(tag)) {
+                    const attrs = openMatch[2];
+                    const allowed = INLINE_ALLOWED_ATTRS[tag] ?? new Set();
+                    const kept = [];
+                    const attrRe = /(\w+)(?:="([^"]*)")?/g;
+                    let m;
+                    while ((m = attrRe.exec(attrs)) !== null) {
+                        const name = m[1].toLowerCase();
+                        if (name.startsWith('on'))
+                            continue;
+                        if (!allowed.has(name))
+                            continue;
+                        if (name === 'href') {
+                            const val = m[2] ?? '';
+                            if (!val || !SAFE_HREF_RE.test(val))
+                                continue;
+                        }
+                        kept.push(` ${name}="${escapeHtml(m[2] ?? '')}"`);
+                    }
+                    out += `<${tag}${kept.join('')}>`;
+                }
+                i += openMatch[0].length;
+                continue;
+            }
+            i += 1;
+        }
+        else if (html[i] === '&') {
+            const entityMatch = html.slice(i).match(/^&(#?\w+);/);
+            if (entityMatch) {
+                out += entityMatch[0];
+                i += entityMatch[0].length;
+            }
+            else {
+                out += '&amp;';
+                i += 1;
+            }
+        }
+        else {
+            out += html[i];
+            i += 1;
+        }
+    }
+    return out;
+}
+const STAT_RE = /<aside\s+data-stat="(?<value>[^"]+)">(?<label>.*?)<\/aside>/gis;
+const QUOTE_RE = /<blockquote\s+(?:data-source="(?<src>[^"]*)"\s*)?(?:data-source-url="(?<url>[^"]*)"\s*)?(?:data-attr="(?<attr>[^"]*)"\s*)?>(?<text>.*?)<\/blockquote>/gis;
+const TAG_STRIP_RE = /<[^>]+>/g;
+function plainStatValue(raw) {
+    return raw.replace(TAG_STRIP_RE, '').trim();
+}
+function transformInlineBlocks(bodyHtml) {
+    return bodyHtml
+        .replace(STAT_RE, (_match, _value, _label, offset, str, groups) => {
+        const value = plainStatValue(groups?.value ?? _value);
+        const label = (groups?.label ?? _label ?? '').trim();
+        return ('<div class="article-stat">' +
+            `<div class="big">${escapeHtml(value)}</div>` +
+            `<div class="lbl">${sanitizeInline(label)}</div>` +
+            '</div>');
+    })
+        .replace(QUOTE_RE, (_match, _src, _url, _attr, _text, offset, str, groups) => {
+        const text = (groups?.text ?? _text ?? '').trim();
+        const attr = groups?.attr ?? _attr ?? '';
+        const url = groups?.url ?? _url ?? '';
+        const src = groups?.src ?? _src ?? '';
+        let attrHtml = '';
+        if (attr || src) {
+            const linkLabel = src || 'Source';
+            const safeUrl = url && SAFE_HREF_RE.test(url) ? url : '';
+            const link = safeUrl
+                ? ` &middot; <a href="${escapeHtml(safeUrl)}">${escapeHtml(linkLabel)}</a>`
+                : '';
+            attrHtml = `<div class="attr">${escapeHtml(attr)}${link}</div>`;
+        }
+        return ('<figure class="source-quote">' +
+            `<p class="q">${sanitizeInline(text)}</p>` +
+            attrHtml +
+            '</figure>');
+    });
+}
+function safeUrl(url) {
+    return SAFE_HREF_RE.test(url) ? url : '';
+}
+export { escapeHtml, sanitizeInline, transformInlineBlocks, safeUrl };

package/dist/frontpage.d.ts

@@ -0,0 +1,8 @@
+import type { ArticleData, RenderOptions } from './types.js';
+export type FrontPageRowType = 'hero' | 'feature' | 'triple' | 'brief';
+export interface FrontPageRow {
+    type: FrontPageRowType;
+    items: ArticleData[];
+}
+export declare function buildFrontPage(items: ArticleData[]): FrontPageRow[];
+export declare function renderFrontPage(rows: FrontPageRow[], opts?: RenderOptions): string;

package/dist/frontpage.js

@@ -0,0 +1,55 @@
+import { escapeHtml, safeUrl } from './format.js';
+import { categoryClass, renderCard } from './render.js';
+const BRIEF_MAX = 5;
+export function buildFrontPage(items) {
+    if (!items.length)
+        return [];
+    const pool = [...items];
+    const hotIdx = pool.findIndex((entry) => entry.hot);
+    if (hotIdx > 0)
+        pool.unshift(pool.splice(hotIdx, 1)[0]);
+    const rows = [{ type: 'hero', items: pool.splice(0, 1) }];
+    if (pool.length >= 2)
+        rows.push({ type: 'feature', items: pool.splice(0, 2) });
+    if (pool.length >= 3)
+        rows.push({ type: 'triple', items: pool.splice(0, 3) });
+    const brief = pool.splice(0, BRIEF_MAX);
+    if (brief.length)
+        rows.push({ type: 'brief', items: brief });
+    return rows;
+}
+function renderHeroCard(data) {
+    const href = safeUrl(data.shareUrl ?? '') || '#';
+    const imgSrc = safeUrl(data.heroImage) || 'data:,';
+    return (`<a class="df-hero-card ${categoryClass(data.category)}" href="${escapeHtml(href)}">` +
+        `<img class="df-hero-img" src="${escapeHtml(imgSrc)}" alt="${escapeHtml(data.heroImageAlt ?? data.title)}" loading="lazy" width="1200" height="675">` +
+        '<div class="df-hero-scrim" aria-hidden="true"></div>' +
+        '<div class="df-hero-text">' +
+        (data.hot ? '<span class="df-hot">HOT</span>' : '') +
+        `<div class="card-kicker">${escapeHtml(data.category)}</div>` +
+        `<h3 class="df-hero-title">${escapeHtml(data.title)}</h3>` +
+        `<p class="df-hero-sub">${escapeHtml(data.subtitle)}</p>` +
+        '</div></a>');
+}
+function renderBriefItem(data) {
+    const href = safeUrl(data.shareUrl ?? '') || '#';
+    return (`<li><a href="${escapeHtml(href)}">` +
+        `<span class="df-brief-title">${escapeHtml(data.title)}</span>` +
+        `<time>${escapeHtml(data.publishedAt)}</time>` +
+        '</a></li>');
+}
+export function renderFrontPage(rows, opts) {
+    const rendered = rows.map((row) => {
+        if (row.type === 'hero') {
+            return `<div class="df-row df-row--hero">${renderHeroCard(row.items[0])}</div>`;
+        }
+        if (row.type === 'brief') {
+            const lis = row.items.map(renderBriefItem).join('');
+            return `<div class="df-row df-row--brief"><div class="df-brief-label">In brief</div><ul>${lis}</ul></div>`;
+        }
+        const cls = row.type === 'feature' ? 'df-row--feature' : 'df-row--triple';
+        const cards = row.items.map((entry) => renderCard(entry, opts)).join('');
+        return `<div class="df-row ${cls}">${cards}</div>`;
+    });
+    return `<div class="druck-front-page">${rendered.join('')}</div>`;
+}

package/dist/frontpage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/frontpage.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { buildFrontPage, renderFrontPage } from './frontpage.js';
+function item(n, extra = {}) {
+    return {
+        title: `Story ${n}`,
+        subtitle: `Subtitle ${n}`,
+        metaDescription: `Meta ${n}`,
+        slug: `story-${n}`,
+        format: 'wire',
+        category: 'ai',
+        publishedAt: 'Jun 10, 2026',
+        heroImage: `https://example.com/${n}.webp`,
+        shareUrl: `https://example.com/articles/story-${n}/`,
+        ...extra,
+    };
+}
+const eleven = Array.from({ length: 11 }, (_, i) => item(i));
+describe('buildFrontPage', () => {
+    it('produces hero, feature, triple, brief for 11 items', () => {
+        const rows = buildFrontPage(eleven);
+        expect(rows.map((r) => r.type)).toEqual(['hero', 'feature', 'triple', 'brief']);
+        expect(rows.map((r) => r.items.length)).toEqual([1, 2, 3, 5]);
+    });
+    it('is deterministic', () => {
+        expect(buildFrontPage(eleven)).toEqual(buildFrontPage(eleven));
+    });
+    it('promotes the first hot item to the hero', () => {
+        const items = [item(0), item(1), item(2, { hot: true })];
+        const rows = buildFrontPage(items);
+        expect(rows[0].items[0].slug).toBe('story-2');
+    });
+    it('degrades gracefully on sparse input', () => {
+        expect(buildFrontPage([])).toEqual([]);
+        expect(buildFrontPage([item(0)]).map((r) => r.type)).toEqual(['hero']);
+        expect(buildFrontPage([item(0), item(1)]).map((r) => r.type)).toEqual(['hero', 'brief']);
+        expect(buildFrontPage(eleven.slice(0, 3)).map((r) => r.type)).toEqual(['hero', 'feature']);
+    });
+    it('caps brief at 5 and ignores overflow', () => {
+        const twenty = Array.from({ length: 20 }, (_, i) => item(i));
+        const rows = buildFrontPage(twenty);
+        expect(rows.at(-1)?.items.length).toBe(5);
+        expect(rows.flatMap((r) => r.items).length).toBe(11);
+    });
+});
+describe('renderFrontPage', () => {
+    it('renders row wrappers and a scrimmed hero card', () => {
+        const html = renderFrontPage(buildFrontPage(eleven));
+        expect(html).toContain('class="druck-front-page"');
+        expect(html).toContain('df-row--hero');
+        expect(html).toContain('df-row--feature');
+        expect(html).toContain('df-row--triple');
+        expect(html).toContain('df-row--brief');
+        expect(html).toContain('df-hero-scrim');
+    });
+    it('renders a HOT badge only for hot heroes', () => {
+        const hot = renderFrontPage(buildFrontPage([item(0, { hot: true })]));
+        const cold = renderFrontPage(buildFrontPage([item(0)]));
+        expect(hot).toContain('df-hot');
+        expect(cold).not.toContain('df-hot');
+    });
+    it('escapes content and drops unsafe URLs', () => {
+        const evil = item(0, {
+            title: '<script>x</script>',
+            shareUrl: 'javascript:alert(1)',
+        });
+        const html = renderFrontPage(buildFrontPage([evil]));
+        expect(html).not.toContain('<script>x');
+        expect(html).not.toContain('javascript:');
+        expect(html).toContain('href="#"');
+    });
+    it('guards an empty hero image src', () => {
+        const html = renderFrontPage(buildFrontPage([item(0, { heroImage: '' })]));
+        expect(html).not.toContain('src=""');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ArticleFormat, ArticleData, Category, Chapter, KeyPoint, StatAside, SourceQuote, Figure, KnowCard, RelatedArticle, WeeklyData, WeeklySection, WeeklySectionArticle, RenderOptions, } from './types.js';
+export { renderArticle, renderCard } from './render.js';
+export { transformInlineBlocks, sanitizeInline, escapeHtml, safeUrl } from './format.js';
+export { buildFrontPage, renderFrontPage } from './frontpage.js';
+export type { FrontPageRow, FrontPageRowType } from './frontpage.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { renderArticle, renderCard } from './render.js';
+export { transformInlineBlocks, sanitizeInline, escapeHtml, safeUrl } from './format.js';
+export { buildFrontPage, renderFrontPage } from './frontpage.js';

package/dist/render.d.ts

@@ -0,0 +1,5 @@
+import type { ArticleData, RenderOptions, WeeklyData } from './types.js';
+export declare function categoryClass(category: string): string;
+export declare function renderArticle(data: ArticleData, opts?: RenderOptions): string;
+export declare function renderWeekly(data: WeeklyData, opts?: RenderOptions): string;
+export declare function renderCard(data: ArticleData, opts?: RenderOptions): string;

package/dist/render.js

@@ -0,0 +1,224 @@
+import { escapeHtml, sanitizeInline, transformInlineBlocks, safeUrl } from './format.js';
+function safeDimension(value, fallback) {
+    return Number.isFinite(value) ? Math.trunc(value) : fallback;
+}
+function titleWithAccent(title, accentWord) {
+    const safe = escapeHtml(title);
+    if (!accentWord)
+        return safe;
+    const safeWord = escapeHtml(accentWord);
+    if (!safe.includes(safeWord))
+        return safe;
+    const idx = safe.indexOf(safeWord);
+    return safe.slice(0, idx) + `<em class="accent-word">${safeWord}</em>` + safe.slice(idx + safeWord.length);
+}
+function renderChapter(num, total, chapter) {
+    const titleHtml = titleWithAccent(chapter.title, chapter.titleAccentWord);
+    const body = transformInlineBlocks(chapter.bodyHtml);
+    return ('<section class="chapter-panel">' +
+        '<div class="chapter-head">' +
+        `<div class="chapter-num">Chapter ${escapeHtml(String(num))} &middot; of ${String(total).padStart(2, '0')}</div>` +
+        `<h2 class="chapter-title">${titleHtml}</h2>` +
+        '</div>' +
+        `<div class="chapter-body">${body}</div>` +
+        '</section>');
+}
+function renderKeyPoints(points) {
+    if (!points?.length)
+        return '';
+    const items = points
+        .slice(0, 3)
+        .map((p, i) => `<div class="kp-item"><div class="n">${String(i + 1).padStart(2, '0')}</div><p>${escapeHtml(p.text)}</p></div>`)
+        .join('');
+    return ('<section class="key-points">' +
+        '<div class="lbl">Three things to know</div>' +
+        `<div class="key-points-grid">${items}</div>` +
+        '</section>');
+}
+function renderKnowCard(items, label, kind) {
+    const lis = items.map((x) => `<li>${escapeHtml(x)}</li>`).join('');
+    return (`<div class="know-card ${kind}">` +
+        `<div class="lbl">${label}</div>` +
+        `<ul>${lis || '<li>&mdash;</li>'}</ul>` +
+        '</div>');
+}
+function renderKnowCards(known, unknown) {
+    const k = known?.items ?? [];
+    const u = unknown?.items ?? [];
+    if (!k.length && !u.length)
+        return '';
+    return ('<aside class="know-cards" role="note">' +
+        renderKnowCard(k, 'What we know', 'yes') +
+        renderKnowCard(u, "What we don't", 'no') +
+        '</aside>');
+}
+function renderEditorsNote(angle, sourceCount) {
+    if (!angle)
+        return '';
+    const siteName = 'Druck';
+    return ('<aside class="editors-note" role="note">' +
+        "<span class=\"lbl\">Editor's note</span> " +
+        `Written by ${siteName}'s editorial agent from <b>${sourceCount ?? 1} sources</b>. ` +
+        `<b>${siteName}'s angle:</b> ${escapeHtml(angle)}` +
+        '</aside>');
+}
+function renderShareBar(title, url) {
+    const shareUrl = url ?? '#';
+    return ('<div class="article-share-bar">' +
+        '<span class="article-share-bar-label">Share this story</span>' +
+        '<div class="article-share-bar-actions">' +
+        `<button class="share-btn-pill" data-share-button data-share-title="${escapeHtml(title)}" data-share-url="${escapeHtml(shareUrl)}" aria-label="Share article">` +
+        '<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+        '<line x1="22" y1="2" x2="11" y2="13"/>' +
+        '<polygon points="22 2 15 22 11 13 2 9 22 2"/>' +
+        '</svg>' +
+        'Share' +
+        '</button>' +
+        '</div>' +
+        '</div>');
+}
+export function categoryClass(category) {
+    return `cat-${category}`;
+}
+function formatLabel(format) {
+    if (format === 'quick_take')
+        return 'Quick Take';
+    if (format === 'feature')
+        return 'Feature';
+    return '';
+}
+function renderRelated(related) {
+    if (!related?.length)
+        return '';
+    const cards = related
+        .map((r) => {
+        const safeRelatedUrl = safeUrl(r.url);
+        if (!safeRelatedUrl)
+            return '';
+        return (`<a class="similar-card" href="${escapeHtml(safeRelatedUrl)}">` +
+            (r.image ? `<img class="sc-img" src="${escapeHtml(safeUrl(r.image))}" alt="" loading="lazy">` : '') +
+            `<div class="sc-text"><div class="sc-title">${escapeHtml(r.title)}</div>` +
+            (r.category ? `<div class="sc-cat">${escapeHtml(r.category)}</div>` : '') +
+            '</div></a>');
+    })
+        .join('');
+    return '<section class="similar-articles">' + cards + '</section>';
+}
+export function renderArticle(data, opts) {
+    const lang = opts?.lang ?? 'en';
+    const catClass = categoryClass(data.category);
+    const titleHtml = titleWithAccent(data.title, data.titleAccentWord);
+    const fLabel = formatLabel(data.format);
+    if (data.format === 'wire') {
+        return renderWireArticle(data, { ...opts, lang, catClass, titleHtml, fLabel });
+    }
+    return renderFeatureArticle(data, { ...opts, lang, catClass, titleHtml, fLabel });
+}
+function renderFeatureArticle(data, ctx) {
+    const chaptersHtml = (data.chapters ?? [])
+        .map((ch, i) => renderChapter(i + 1, data.chapters.length, ch))
+        .join('');
+    const bodyHtml = transformInlineBlocks(data.bodyHtml ?? chaptersHtml);
+    const readingSpan = data.readingTime ? `<span>${escapeHtml(data.readingTime)}</span>` : '';
+    const byline = data.byline
+        ? `<span>${escapeHtml(data.byline.author)}</span><span>${escapeHtml(data.byline.date)}</span>${readingSpan}`
+        : `<span>By Editorial</span>${readingSpan}`;
+    return (`<article class="article-shell ${ctx.catClass}">` +
+        '<div class="article-progress" aria-hidden="true"><div class="fill"></div></div>' +
+        '<header class="article-hero">' +
+        '<div class="article-hero-inner">' +
+        `<div class="article-kicker">${escapeHtml(data.category)}${ctx.fLabel ? ` <span class="sep">&middot;</span> ${ctx.fLabel}` : ''}</div>` +
+        `<h1 class="article-title">${ctx.titleHtml}</h1>` +
+        `<p class="article-deck">${escapeHtml(data.subtitle)}</p>` +
+        `<div class="article-byline">${byline}</div>` +
+        '</div>' +
+        '</header>' +
+        `<figure class="article-hero-img"><img src="${escapeHtml(safeUrl(data.heroImage))}" alt="${escapeHtml(data.heroImageAlt ?? data.title)}" loading="eager" fetchpriority="high" width="${safeDimension(data.heroImageWidth, 1920)}" height="${safeDimension(data.heroImageHeight, 1080)}"></figure>` +
+        renderEditorsNote(data.editorsNote, data.sourceCount) +
+        `<div class="article-body">${bodyHtml}</div>` +
+        renderKeyPoints(data.keyPoints) +
+        renderKnowCards(data.known, data.unknown) +
+        renderRelated(data.related) +
+        renderShareBar(data.title, data.shareUrl) +
+        '</article>');
+}
+function renderWireArticle(data, ctx) {
+    const bodyHtml = transformInlineBlocks(data.bodyHtml ?? '');
+    return (`<article class="post-simple ${ctx.catClass}">` +
+        '<header class="post-simple-head">' +
+        `<div class="post-simple-kicker">${escapeHtml(data.category)}</div>` +
+        `<h1 class="post-simple-title">${ctx.titleHtml}</h1>` +
+        `<div class="post-simple-meta"><span>${escapeHtml(data.publishedAt)}</span>${data.readingTime ? `<span>${escapeHtml(data.readingTime)}</span>` : ''}</div>` +
+        '</header>' +
+        `<figure class="post-simple-img"><img src="${escapeHtml(safeUrl(data.heroImage))}" alt="${escapeHtml(data.heroImageAlt ?? data.title)}" loading="eager" fetchpriority="high" decoding="async" width="${safeDimension(data.heroImageWidth, 1600)}" height="${safeDimension(data.heroImageHeight, 900)}"></figure>` +
+        `<div class="post-simple-body">${bodyHtml}</div>` +
+        (data.pullQuote
+            ? `<figure class="source-quote"><p class="q">${sanitizeInline(data.pullQuote)}</p></figure>`
+            : '') +
+        (data.whyItMatters
+            ? `<aside class="editors-note" role="note"><span class="lbl">Why it matters</span> ${escapeHtml(data.whyItMatters)}</aside>`
+            : '') +
+        renderRelated(data.related) +
+        renderShareBar(data.title, data.shareUrl) +
+        '</article>');
+}
+export function renderWeekly(data, opts) {
+    const sectionsHtml = data.sections
+        .map((s) => renderWeeklySection(s))
+        .join('');
+    return (`<article class="article-shell cat-weekly">` +
+        '<div class="article-progress" aria-hidden="true"><div class="fill"></div></div>' +
+        '<header class="article-hero">' +
+        '<div class="article-hero-inner">' +
+        '<div class="article-kicker">Weekly Recap</div>' +
+        `<h1 class="article-title">${escapeHtml(data.title)}</h1>` +
+        `<p class="article-deck">${escapeHtml(data.subtitle)}</p>` +
+        '</div>' +
+        '</header>' +
+        `<figure class="article-hero-img"><img src="${escapeHtml(safeUrl(data.heroImage))}" alt="${escapeHtml(data.title)}" loading="eager" width="1920" height="1080"></figure>` +
+        `<div class="recap-thesis">${escapeHtml(data.thesis)}</div>` +
+        `<div class="article-body">${sectionsHtml}</div>` +
+        renderKeyPoints(data.keyPoints) +
+        renderKnowCards(data.known, data.unknown) +
+        renderRelated(data.related) +
+        renderShareBar(data.title, data.shareUrl) +
+        '</article>');
+}
+export function renderCard(data, opts) {
+    const catClass = categoryClass(data.category);
+    const titleHtml = titleWithAccent(data.title, data.titleAccentWord);
+    const fLabel = formatLabel(data.format);
+    const rawHref = data.shareUrl ?? `#${data.slug}`;
+    const href = safeUrl(rawHref) || '#';
+    return (`<a class="druck-card ${catClass}" href="${escapeHtml(href)}">` +
+        `<figure class="card-thumb"><img src="${escapeHtml(safeUrl(data.heroImage))}" alt="${escapeHtml(data.heroImageAlt ?? data.title)}" loading="lazy" width="400" height="225"></figure>` +
+        `<div class="card-text">` +
+        `<div class="card-kicker">${escapeHtml(data.category)}${fLabel ? ` <span class="sep">&middot;</span> ${fLabel}` : ''}</div>` +
+        `<h3 class="card-title">${titleHtml}</h3>` +
+        `<p class="card-subtitle">${escapeHtml(data.subtitle)}</p>` +
+        `<div class="card-meta"><time>${escapeHtml(data.publishedAt)}</time>${data.readingTime ? `<span>${escapeHtml(data.readingTime)}</span>` : ''}</div>` +
+        `</div>` +
+        `</a>`);
+}
+function renderWeeklySection(section) {
+    const narrativeHtml = transformInlineBlocks(section.narrative);
+    const keyPointsHtml = renderKeyPoints(section.keyPoints);
+    const articlesHtml = (section.articles ?? [])
+        .map((a) => {
+        const safeArticleUrl = safeUrl(a.url);
+        if (!safeArticleUrl)
+            return '';
+        return (`<a class="recap-article" href="${escapeHtml(safeArticleUrl)}">` +
+            (a.image ? `<img class="recap-article-thumb" src="${escapeHtml(safeUrl(a.image))}" alt="" loading="lazy">` : '') +
+            `<div class="recap-article-title">${escapeHtml(a.title)}</div>` +
+            (a.summary ? `<div class="recap-article-summary">${escapeHtml(a.summary)}</div>` : '') +
+            '</a>');
+    })
+        .join('');
+    return ('<section class="chapter-panel recap-section">' +
+        `<h2 class="recap-section-title">${escapeHtml(section.title)}</h2>` +
+        `<div class="recap-section-narrative">${narrativeHtml}</div>` +
+        keyPointsHtml +
+        (articlesHtml ? `<div class="recap-articles">${articlesHtml}</div>` : '') +
+        '</section>');
+}

package/dist/render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/render.test.js

@@ -0,0 +1,116 @@
+import { describe, expect, test } from 'vitest';
+import { renderArticle, renderCard } from './render.js';
+function buildArticle(overrides = {}) {
+    return {
+        title: 'Test Story',
+        subtitle: 'A subtitle',
+        metaDescription: 'meta',
+        slug: 'test-story',
+        format: 'feature',
+        category: 'ai',
+        publishedAt: '2026-06-09',
+        readingTime: '3 min read',
+        heroImage: '/img/test.webp',
+        chapters: [{ title: 'One', bodyHtml: '<p>Body</p>' }],
+        ...overrides,
+    };
+}
+describe('hero image attributes', () => {
+    test('emits provided alt text and dimensions on feature heroes', () => {
+        const html = renderArticle(buildArticle({ heroImageAlt: 'Abstract circuitry', heroImageWidth: 1920, heroImageHeight: 1047 }));
+        expect(html).toContain('alt="Abstract circuitry"');
+        expect(html).toContain('width="1920"');
+        expect(html).toContain('height="1047"');
+    });
+    test('falls back to title alt and template dimensions when fields absent', () => {
+        const html = renderArticle(buildArticle());
+        expect(html).toContain('alt="Test Story"');
+        expect(html).toContain('width="1920"');
+        expect(html).toContain('height="1080"');
+    });
+    test('emits provided dimensions on wire heroes', () => {
+        const html = renderArticle(buildArticle({ format: 'wire', bodyHtml: '<p>Wire body</p>', heroImageWidth: 1920, heroImageHeight: 1049 }));
+        expect(html).toContain('width="1920"');
+        expect(html).toContain('height="1049"');
+    });
+    test('escapes html-special characters in heroImageAlt', () => {
+        const html = renderArticle(buildArticle({ heroImageAlt: '"onload="alert(1)' }));
+        expect(html).not.toContain('"onload=');
+        expect(html).toContain('&quot;');
+    });
+    test('rejects non-numeric hero dimensions to prevent attribute injection', () => {
+        const malicious = { heroImageWidth: '800" onload="alert(1)' };
+        const html = renderArticle(buildArticle(malicious));
+        expect(html).not.toContain('onload=');
+        expect(html).toContain('width="1920"');
+    });
+    test('falls back to wire template dimensions when fields absent', () => {
+        const html = renderArticle(buildArticle({ format: 'wire', bodyHtml: '<p>Wire body</p>', chapters: undefined }));
+        expect(html).toContain('width="1600"');
+        expect(html).toContain('height="900"');
+    });
+});
+describe('renderCard', () => {
+    test('emits card markup with category class and kicker', () => {
+        const html = renderCard(buildArticle({ format: 'quick_take' }));
+        expect(html).toContain('class="druck-card cat-ai"');
+        expect(html).toContain('class="card-thumb"');
+        expect(html).toContain('class="card-title"');
+        expect(html).toContain('ai');
+        expect(html).toContain('Quick Take');
+        expect(html).toContain('Test Story');
+        expect(html).toContain('A subtitle');
+    });
+    test('uses shareUrl as href when present', () => {
+        const html = renderCard(buildArticle({ shareUrl: '/articles/test/' }));
+        expect(html).toContain('href="/articles/test/"');
+    });
+    test('falls back to slug hash when shareUrl absent', () => {
+        const html = renderCard(buildArticle());
+        expect(html).toContain('href="#test-story"');
+    });
+    test('escapes title and subtitle in card output', () => {
+        const html = renderCard(buildArticle({ title: '<script>', subtitle: '"alert"' }));
+        expect(html).not.toContain('<script>');
+        expect(html).toContain('&lt;script&gt;');
+        expect(html).toContain('&quot;alert&quot;');
+    });
+    test('strips javascript: URLs from card href', () => {
+        const html = renderCard(buildArticle({ shareUrl: 'javascript:alert(1)' }));
+        expect(html).not.toContain('javascript:');
+        expect(html).toContain('href="\#"');
+    });
+    test('strips data: URLs from hero image src', () => {
+        const html = renderArticle(buildArticle({ heroImage: 'data:image/svg+xml,<svg></svg>' }));
+        expect(html).not.toContain('data:');
+        expect(html).toContain('src=""');
+    });
+    test('preserves safe relative and absolute URLs', () => {
+        const html = renderCard(buildArticle({ shareUrl: '/articles/safe/', heroImage: 'https://example.com/img.webp' }));
+        expect(html).toContain('href="/articles/safe/"');
+        expect(html).toContain('src="https://example.com/img.webp"');
+    });
+    test('omits the reading-time span when readingTime is absent', () => {
+        const html = renderCard(buildArticle({ readingTime: undefined }));
+        expect(html).not.toContain('<span></span>');
+        expect(html).toContain('<time>');
+    });
+    test('accepts the widened category union', () => {
+        const html = renderCard(buildArticle({ category: 'infrastructure' }));
+        expect(html).toContain('cat-infrastructure');
+    });
+});
+describe('renderArticle feature format', () => {
+    test('omits reading-time span in byline when readingTime is absent', () => {
+        const html = renderArticle(buildArticle({ format: 'feature', readingTime: undefined }));
+        expect(html).not.toContain('<span></span>');
+        expect(html).toContain('article-byline');
+    });
+});
+describe('renderArticle wire format', () => {
+    test('omits reading-time span in meta when readingTime is absent', () => {
+        const html = renderArticle(buildArticle({ format: 'wire', readingTime: undefined, bodyHtml: '<p>Wire body</p>' }));
+        expect(html).not.toContain('<span></span>');
+        expect(html).toContain('post-simple-meta');
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+export type ArticleFormat = 'feature' | 'quick_take' | 'wire';
+export type Category = 'ai' | 'dev' | 'dev-tools' | 'security' | 'infrastructure' | 'policy' | 'startup' | 'business' | 'science' | 'general' | 'weekly';
+export interface Chapter {
+    title: string;
+    titleAccentWord?: string;
+    bodyHtml: string;
+}
+export interface KeyPoint {
+    text: string;
+}
+export interface StatAside {
+    value: string;
+    label: string;
+}
+export interface SourceQuote {
+    text: string;
+    attribution?: string;
+    source?: string;
+    sourceUrl?: string;
+}
+export interface Figure {
+    src: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+}
+export interface KnowCard {
+    items: string[];
+}
+export interface ArticleData {
+    title: string;
+    titleAccentWord?: string;
+    subtitle: string;
+    metaDescription: string;
+    slug: string;
+    format: ArticleFormat;
+    hot?: boolean;
+    category: Category;
+    publishedAt: string;
+    readingTime?: string;
+    heroImage: string;
+    heroImageAlt?: string;
+    heroImageWidth?: number;
+    heroImageHeight?: number;
+    heroCaption?: string;
+    byline?: {
+        author: string;
+        date: string;
+    };
+    lens?: string;
+    lensRationale?: string;
+    chapters?: Chapter[];
+    keyPoints?: KeyPoint[];
+    known?: KnowCard;
+    unknown?: KnowCard;
+    editorsNote?: string;
+    sourceCount?: number;
+    stats?: StatAside[];
+    quotes?: SourceQuote[];
+    figures?: Figure[];
+    bodyHtml?: string;
+    pullQuote?: string;
+    whyItMatters?: string;
+    shareUrl?: string;
+    related?: RelatedArticle[];
+}
+export interface RelatedArticle {
+    title: string;
+    url: string;
+    category?: Category;
+    image?: string;
+}
+export interface WeeklyData {
+    title: string;
+    subtitle: string;
+    metaDescription: string;
+    slug: string;
+    date: string;
+    heroImage: string;
+    thesis: string;
+    sections: WeeklySection[];
+    keyPoints?: KeyPoint[];
+    known?: KnowCard;
+    unknown?: KnowCard;
+    shareUrl?: string;
+    related?: RelatedArticle[];
+}
+export interface WeeklySection {
+    title: string;
+    narrative: string;
+    keyPoints?: KeyPoint[];
+    articles?: WeeklySectionArticle[];
+}
+export interface WeeklySectionArticle {
+    title: string;
+    url: string;
+    category?: Category;
+    image?: string;
+    summary?: string;
+}
+export interface RenderOptions {
+    lang?: string;
+    theme?: 'light' | 'dark';
+    accentColor?: string;
+    siteName?: string;
+    siteUrl?: string;
+    canonicalUrl?: string;
+    ogImageUrl?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@druck-editorial/engine",
+  "version": "0.1.0",
+  "description": "Editorial rendering engine: structured article JSON in, magazine-quality pages out.",
+  "author": "Artem Iagovdik <artyom.yagovdik@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/druck-editorial/druck.git",
+    "directory": "packages/druck-engine"
+  },
+  "homepage": "https://github.com/druck-editorial/druck",
+  "keywords": [
+    "editorial",
+    "typography",
+    "rendering",
+    "magazine",
+    "web-components"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}