@astryxdesign/cli 0.1.2-canary.bfcbf64 → 0.1.2-canary.c11faf5

package/docs/layout.doc.dense.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsDense = {
+  description:
+    'frame-first app layout: shell choice, region budgets, cards vs rows',
+  sections: [
+    {
+      title: 'Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
+        },
+        {
+          type: 'list',
+          items: [
+            'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',
+            'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',
+            'container policy per region: dense data = rows; dashboards/galleries = card grids',
+            'write responsive contract up front',
+          ],
+        },
+        null,
+      ],
+    },
+    {
+      title: 'App Archetypes',
+      content: [
+        {
+          type: 'prose',
+          text: 'container choice tracks archetype, not preference.',
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'start from matching template (astryx template --list), study with --skeleton.',
+        },
+      ],
+    },
+    {
+      title: 'Cards vs Rows',
+      content: [
+        {
+          type: 'prose',
+          text: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',
+        },
+        {
+          type: 'list',
+          items: [
+            'Table+plugins: hosts, deployments, monitors, users',
+            'List/Item rows: issues, files, conversations',
+            'Card: KPI tiles, chart panels, gallery entries, settings groups',
+            'EmptyState for zero-match',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'no Card-wrapped list items (card soup)',
+            'no stacked full-width Cards as page structure',
+            'no Cards in Cards',
+            'no decorative Badge — counts/enums only; StatusDot/Token for status',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Panels and Inspectors',
+      content: [
+        {
+          type: 'prose',
+          text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
+        },
+        null,
+      ],
+    },
+    {
+      title: 'Responsive Contract',
+      content: [
+        {
+          type: 'prose',
+          text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
+        },
+        null,
+      ],
+    },
+  ],
+};

package/docs/layout.doc.mjs

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'layout',
+  title: 'Layout',
+  category: 'guide',
+  description:
+    'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',
+
+  sections: [
+    {
+      title: 'Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)',
+            'Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260',
+            'Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)',
+            'Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'A three-region tool frame',
+          code: `// Frame: nav 256 | content flex | inspector 380 (resizable)
+<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>
+  <Layout>
+    <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>
+    <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>
+      {/* inspector for the selected row */}
+    </LayoutPanel>
+  </Layout>
+</AppShell>`,
+        },
+      ],
+    },
+    {
+      title: 'App Archetypes',
+      content: [
+        {
+          type: 'prose',
+          text: 'Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.',
+        },
+        {
+          type: 'table',
+          headers: ['Archetype', 'Frame', 'Container policy'],
+          rows: [
+            [
+              'Tracker / work tool (issues, tickets, CRM)',
+              'AppShell + SideNav; inspector LayoutPanel on select',
+              'Rows only. Grouped edge-to-edge lists, zero cards',
+            ],
+            [
+              'Console / observability (metrics, logs, deploys)',
+              'AppShell + SideNav or TopNav + TabList',
+              'Card grid for dashboard widgets; Table for everything else',
+            ],
+            [
+              'Messaging / feed',
+              'Column frame: rail + sidebar + stream + panel',
+              'Rows and bubbles. No cards in the stream',
+            ],
+            [
+              'Media library / gallery',
+              'AppShell + TopNav; grid content',
+              'Card grid (ClickableCard) with dense metadata rows in detail views',
+            ],
+            [
+              'Settings / forms',
+              'AppShell + SideNav or settings template',
+              'Sections with FormLayout; Card only to group dangerous or billing actions',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',
+        },
+      ],
+    },
+    {
+      title: 'Cards vs Rows',
+      content: [
+        {
+          type: 'prose',
+          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data — anything the user scans, filters, or selects — belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
+        },
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users',
+            'List/Item rows for scannable single-line records: issues, files, conversations',
+            'Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups',
+            'EmptyState inside the region when a filter matches nothing',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Wrapping each list item in a Card (card soup)',
+            'Stacking full-width Cards as a substitute for page structure',
+            'Nesting Cards inside Cards',
+            'Using Badge as decoration — reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Panels and Inspectors',
+      content: [
+        {
+          type: 'prose',
+          text: 'Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Inspector that overlays at narrow widths',
+          code: `<LayoutPanel
+  width={380}
+  hasDivider
+  isScrollable
+  label="Details"
+  resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>
+  {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}
+</LayoutPanel>`,
+        },
+      ],
+    },
+    {
+      title: 'Responsive Contract',
+      content: [
+        {
+          type: 'prose',
+          text: 'Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Contract comment at the frame root',
+          code: `// Responsive contract:
+//   > 1024px  nav 256 | content | inspector 380
+//   <= 1024px inspector overlays content (position: absolute, end-aligned)
+//   <= 768px  nav collapses into MobileNav drawer; toolbar actions wrap`,
+        },
+      ],
+    },
+  ],
+};

package/docs/principles.doc.dense.mjs

@@ -6,9 +6,9 @@ export const docsDense = {
   description: 'core design principles + rules for the design system',
   sections: [
     { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
-    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
+    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
     { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
-    { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'read docs before inventing props'] }] },
+    { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
     { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
   ],
 };

package/docs/principles.doc.mjs

@@ -39,6 +39,8 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
+            'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx astryx docs layout\`)',
+            'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
             'StyleX or Tailwind for custom styling; both are first-class (see \`npx astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
             'CSS custom properties for colors, not hex values',
@@ -74,6 +76,8 @@ export const docs = {
             'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
             'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
             'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`npx astryx docs layout\`)',
+            'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
             'Inventing props. Read component docs first',
           ],
         },

package/docs/principles.doc.zh.mjs

@@ -6,9 +6,9 @@ export const docsZh = {
   description: 'XDS 核心设计原则和规则。',
   sections: [
     { title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
-    { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
+    { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先：先选定外壳并规划区域尺寸，再编写内容（见 astryx docs layout）', '密集数据使用行（Table、List/Item）通栏渲染；Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
     { title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
-    { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要自创属性。先阅读组件文档'] }] },
+    { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架，密集数据用行渲染（见 astryx docs layout）', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
     { title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.bfcbf64",
+  "version": "0.1.2-canary.c11faf5",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.bfcbf64",
-    "@astryxdesign/lab": "0.1.2-canary.bfcbf64",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.bfcbf64",
+    "@astryxdesign/core": "0.1.2-canary.c11faf5",
+    "@astryxdesign/lab": "0.1.2-canary.c11faf5",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.c11faf5",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.bfcbf64",
-    "@astryxdesign/lab": "0.1.2-canary.bfcbf64",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.bfcbf64",
+    "@astryxdesign/core": "0.1.2-canary.c11faf5",
+    "@astryxdesign/lab": "0.1.2-canary.c11faf5",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.c11faf5",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/blog.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the blog command.
+ *
+ * The blog is read the same way any feed reader reads it: over the published
+ * RSS feed. Listing parses the feed; reading a post fetches the plaintext
+ * (.txt) alternate the feed advertises for each item. Nothing here touches the
+ * blog's source files — the CLI is just a consumer of the public feed, so the
+ * blog's structure can change freely without touching the CLI.
+ */
+
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
+
+/** Abort a feed/post fetch that hangs, and cap how much we'll read. */
+const FETCH_TIMEOUT_MS = 15000;
+const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
+
+const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
+
+async function fetchText(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url, {
+      signal: controller.signal,
+      redirect: 'follow',
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
+    throw new AstryxError(
+      `Could not reach ${url}: ${reason}`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+  clearTimeout(timer);
+  if (!res.ok) {
+    throw new AstryxError(
+      `Request to ${url} failed with ${res.status}`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+  const body = await res.text();
+  if (body.length > MAX_BYTES) {
+    throw new AstryxError(
+      `Response from ${url} exceeded ${MAX_BYTES} bytes`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+  return body;
+}
+
+/**
+ * Defense in depth: a post's plaintext URL comes from feed content. Require it
+ * to live on the canonical origin so even a tampered feed can't redirect the
+ * CLI to another host.
+ */
+function assertCanonicalOrigin(target) {
+  let targetOrigin;
+  try {
+    targetOrigin = new URL(target).origin;
+  } catch {
+    throw new AstryxError(
+      `Post has an invalid plaintext URL: "${target}"`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+  if (targetOrigin !== SITE_ORIGIN) {
+    throw new AstryxError(
+      `Refusing to fetch post text from a non-canonical origin (${targetOrigin})`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+}
+
+function unescapeXml(value) {
+  return value
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function tag(item, name) {
+  const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
+  return m ? unescapeXml(m[1].trim()) : '';
+}
+
+function tagAll(item, name) {
+  const out = [];
+  const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
+  let m;
+  while ((m = re.exec(item))) out.push(unescapeXml(m[1].trim()));
+  return out;
+}
+
+/** Extract the plaintext alternate href from an <item>. */
+function textHref(item) {
+  // Match the atom:link alternate regardless of attribute order/quoting; then
+  // confirm it's the text/plain alternate before trusting the href.
+  const re = /<atom:link\b[^>]*?\/?>/g;
+  let m;
+  while ((m = re.exec(item))) {
+    const el = m[0];
+    if (/rel\s*=\s*["']alternate["']/.test(el) &&
+        /type\s*=\s*["']text\/plain["']/.test(el)) {
+      const href = el.match(/href\s*=\s*["']([^"']+)["']/);
+      if (href) return unescapeXml(href[1]);
+    }
+  }
+  return null;
+}
+
+/** Derive a slug from a post link (last path segment). */
+function slugFromLink(link) {
+  try {
+    const path = new URL(link).pathname.replace(/\/$/, '');
+    return path.slice(path.lastIndexOf('/') + 1);
+  } catch {
+    return link;
+  }
+}
+
+function parseFeed(xml) {
+  const items = [];
+  const re = /<item>([\s\S]*?)<\/item>/g;
+  let m;
+  while ((m = re.exec(xml))) {
+    const raw = m[1];
+    const link = tag(raw, 'link');
+    items.push({
+      slug: slugFromLink(link),
+      title: tag(raw, 'title'),
+      description: tag(raw, 'description'),
+      date: tag(raw, 'pubDate'),
+      type: tag(raw, 'category'),
+      authors: tagAll(raw, 'author'),
+      link,
+      textUrl: textHref(raw),
+    });
+  }
+  return items;
+}
+
+/**
+ * List posts (from the feed), or read one post (via its .txt alternate).
+ * Both envelopes carry `feedUrl` so a caller can hit the RSS feed directly.
+ * The feed is always the canonical site — there is no user-supplied URL.
+ *
+ * @param {string} [slug]
+ * @returns {Promise<{type: string, data: unknown}>}
+ */
+export async function blog(slug) {
+  const xml = await fetchText(FEED_URL);
+  const posts = parseFeed(xml);
+
+  if (!slug) {
+    return {type: 'blog.list', data: {feedUrl: FEED_URL, posts}};
+  }
+
+  const normalized = slug.toLowerCase();
+  const post = posts.find(p => p.slug.toLowerCase() === normalized);
+  if (!post) {
+    throw new AstryxError(
+      `No blog post with slug "${slug}"`,
+      posts.map(p => ({name: p.slug, reason: 'available post'})),
+      ERROR_CODES.ERR_UNKNOWN_POST,
+    );
+  }
+
+  if (!post.textUrl) {
+    throw new AstryxError(
+      `Post "${slug}" has no plaintext alternate in the feed`,
+      [],
+      ERROR_CODES.ERR_FETCH_FAILED,
+    );
+  }
+
+  assertCanonicalOrigin(post.textUrl);
+  const text = await fetchText(post.textUrl);
+  return {type: 'blog.detail', data: {...post, feedUrl: FEED_URL, text}};
+}

package/src/api/blog.test.mjs

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the blog API — reads the blog over the canonical RSS feed
+ * and fetches each post's plaintext (.txt) alternate. `fetch` is stubbed so
+ * the tests never hit the network. The feed origin is fixed (not
+ * user-configurable), so the tests assert the canonical URLs directly.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {blog} from './blog.mjs';
+import {AstryxError} from './error.mjs';
+import {SITE_URL} from '../lib/site.mjs';
+
+const FEED = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>Astryx Blog</title>
+    <link>${SITE_URL}/blog</link>
+    <item>
+      <title>How Astryx works</title>
+      <link>${SITE_URL}/blog/how-astryx-works</link>
+      <guid isPermaLink="true">${SITE_URL}/blog/how-astryx-works</guid>
+      <description>Under the hood &amp; more</description>
+      <category>engineering</category>
+      <author>cvkxx</author>
+      <author>cixzhang</author>
+      <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
+      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
+    </item>
+    <item>
+      <title>Introducing Astryx</title>
+      <link>${SITE_URL}/blog/introducing-astryx</link>
+      <guid isPermaLink="true">${SITE_URL}/blog/introducing-astryx</guid>
+      <description>The launch</description>
+      <category>update</category>
+      <author>cvkxx</author>
+      <pubDate>Thu, 18 Jun 2026 00:00:00 GMT</pubDate>
+      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/introducing-astryx.txt" />
+    </item>
+  </channel>
+</rss>`;
+
+const POST_TEXT = '# How Astryx works\n\nThe body of the post.';
+const FEED_URL = `${SITE_URL}/rss.xml`;
+const TXT_URL = `${SITE_URL}/blog/how-astryx-works.txt`;
+
+/** Build a fetch stub from a url→{status,body} map. */
+function stubFetch(routes) {
+  return vi.fn(async (url, opts) => {
+    const u = String(url);
+    const r = routes[u];
+    if (!r) return {ok: false, status: 404, text: async () => 'not found'};
+    if (r.throw) throw r.throw;
+    return {ok: r.status < 400, status: r.status, text: async () => r.body};
+  });
+}
+
+beforeEach(() => {
+  vi.stubGlobal('fetch', stubFetch({
+    [FEED_URL]: {status: 200, body: FEED},
+    [TXT_URL]: {status: 200, body: POST_TEXT},
+    [`${SITE_URL}/blog/introducing-astryx.txt`]: {status: 200, body: 'launch body'},
+  }));
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('blog API', () => {
+  it('lists posts parsed from the canonical feed', async () => {
+    const res = await blog();
+    expect(res.type).toBe('blog.list');
+    expect(res.data.feedUrl).toBe(FEED_URL);
+    expect(res.data.posts.map(p => p.slug)).toEqual([
+      'how-astryx-works',
+      'introducing-astryx',
+    ]);
+    expect(res.data.posts[0].authors).toEqual(['cvkxx', 'cixzhang']);
+    expect(res.data.posts[0].textUrl).toBe(TXT_URL);
+    // Entity decoding works (&amp; -> &).
+    expect(res.data.posts[0].description).toBe('Under the hood & more');
+    // The list never fetches post bodies.
+    expect(res.data.posts[0].text).toBeUndefined();
+  });
+
+  it('reads a post via its plaintext alternate', async () => {
+    const res = await blog('how-astryx-works');
+    expect(res.type).toBe('blog.detail');
+    expect(res.data.text).toBe(POST_TEXT);
+    expect(res.data.feedUrl).toBe(FEED_URL);
+    expect(fetch).toHaveBeenCalledWith(TXT_URL, expect.any(Object));
+  });
+
+  it('is case-insensitive on the slug', async () => {
+    const res = await blog('How-Astryx-Works');
+    expect(res.data.slug).toBe('how-astryx-works');
+  });
+
+  it('throws ERR_UNKNOWN_POST with suggestions for a bad slug', async () => {
+    await expect(blog('does-not-exist')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_POST',
+    });
+    try {
+      await blog('does-not-exist');
+    } catch (e) {
+      expect(e).toBeInstanceOf(AstryxError);
+      expect(Array.isArray(e.suggestions)).toBe(true);
+      expect(e.suggestions.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('throws ERR_FETCH_FAILED when the feed request fails', async () => {
+    vi.stubGlobal('fetch', stubFetch({
+      [FEED_URL]: {status: 500, body: 'boom'},
+    }));
+    await expect(blog()).rejects.toMatchObject({code: 'ERR_FETCH_FAILED'});
+  });
+
+  it('refuses a post whose plaintext URL is on a different origin (SSRF guard)', async () => {
+    const evilFeed = FEED.replace(
+      `${SITE_URL}/blog/how-astryx-works.txt`,
+      'http://169.254.169.254/latest/meta-data',
+    );
+    vi.stubGlobal('fetch', stubFetch({
+      [FEED_URL]: {status: 200, body: evilFeed},
+      'http://169.254.169.254/latest/meta-data': {status: 200, body: 'SECRETS'},
+    }));
+    await expect(blog('how-astryx-works')).rejects.toMatchObject({
+      code: 'ERR_FETCH_FAILED',
+    });
+    // The internal host must never be fetched.
+    expect(fetch).not.toHaveBeenCalledWith(
+      'http://169.254.169.254/latest/meta-data',
+      expect.anything(),
+    );
+  });
+
+  it('always reads from the canonical feed URL', async () => {
+    await blog();
+    expect(fetch).toHaveBeenCalledWith(FEED_URL, expect.any(Object));
+  });
+});

package/src/api/index.mjs

@@ -21,6 +21,7 @@
 
 export {component} from './component.mjs';
 export {docs} from './docs.mjs';
+export {blog} from './blog.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
 export {themeAdd, listThemes} from './theme-add.mjs';