@astryxdesign/cli 0.1.2-canary.ff01f6d → 0.1.3-canary.6d57c8d

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/doctor.mjs

@@ -240,7 +240,7 @@ export function checkThemes(ctx) {
       label: 'Theme packages',
       status: 'warn',
       message: 'No @astryxdesign/theme-* packages are installed.',
-      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.',
+      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.',
     };
   }
 
@@ -354,7 +354,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',
+      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
     };
   }
 
@@ -362,7 +362,7 @@ export function checkAgentDocs(ctx) {
     id: 'agent-docs',
     label: 'AI agent docs',
     status: 'pass',
-    message: `XDS agent docs section present in ${withMarkers.join(', ')}.`,
+    message: `Astryx agent docs section present in ${withMarkers.join(', ')}.`,
   };
 }
 

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';

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.css') {
+  const {default: transform} = await import('../migrate-xds-css-surfaces.mjs');
+  // api.jscodeshift is unused by this CSS codemod, but the runner still
+  // passes it — mirror that shape.
+  const jscodeshift = (await import('jscodeshift')).default;
+  const api = {jscodeshift, stats: () => {}, report: () => {}};
+  const file = {source, path: filePath};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('migrate-xds-css-surfaces', () => {
+  it('rewrites the .xds- class-selector prefix', async () => {
+    const input = '.xds-heading { color: red; }';
+    const output = await applyTransform(input);
+    expect(output).toBe('.astryx-heading { color: red; }');
+  });
+
+  it('rewrites the [data-xds-theme] attribute selector', async () => {
+    const input = '[data-xds-theme="dark"] .xds-card { background: black; }';
+    const output = await applyTransform(input);
+    expect(output).toContain('[data-astryx-theme="dark"]');
+    expect(output).toContain('.astryx-card');
+    expect(output).not.toContain('xds-');
+  });
+
+  it('rewrites data-xds-theme-prose and data-xds-media attribute selectors', async () => {
+    const input =
+      '[data-xds-theme-prose] {} [data-xds-media="print"] {}';
+    const output = await applyTransform(input);
+    expect(output).toContain('[data-astryx-theme-prose]');
+    expect(output).toContain('[data-astryx-media="print"]');
+  });
+
+  it('rewrites @layer xds-theme and @layer xds-base', async () => {
+    const input = '@layer xds-theme, xds-base;\n@layer xds-theme { a { color: red; } }';
+    const output = await applyTransform(input);
+    expect(output).toContain('astryx-theme');
+    expect(output).toContain('astryx-base');
+    expect(output).not.toContain('xds-theme');
+    expect(output).not.toContain('xds-base');
+  });
+
+  it('does NOT rewrite a bare "xds" in a comment or value', async () => {
+    const input = '/* xds tokens live here */\n.card { content: "xds"; }';
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does NOT rewrite a class-like word missing the leading dot', async () => {
+    // e.g. inside a JS-ish string or a comment fragment — not a class selector.
+    const input = '/* use xds-heading in markup */';
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('leaves already-migrated CSS unchanged', async () => {
+    const input =
+      '@layer astryx-theme { [data-astryx-theme="dark"] .astryx-card {} }';
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+});

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-declare-module.test.mjs

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.d.ts') {
+  const {default: transform} = await import('../migrate-xds-declare-module.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: filePath};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('migrate-xds-declare-module', () => {
+  it('renames a subpath declare module', async () => {
+    const input = [
+      "declare module '@xds/core/Heading' {",
+      '  export const HeadingLevelMap: Record<string, number>;',
+      '}',
+    ].join('\n');
+
+    const output = await applyTransform(input);
+    expect(output).toMatch(/declare module ['"]@astryxdesign\/core\/Heading['"]/);
+    expect(output).not.toContain('@xds/core');
+    // The augmentation body identifier is untouched.
+    expect(output).toContain('HeadingLevelMap');
+  });
+
+  it('renames a bare @xds/core declare module', async () => {
+    const input = "declare module '@xds/core' {\n  const x: number;\n}";
+    const output = await applyTransform(input);
+    expect(output).toMatch(/declare module ['"]@astryxdesign\/core['"]/);
+    expect(output).not.toContain('@xds/core');
+  });
+
+  it('renames @xds/lab declare module using the shared map', async () => {
+    const input = "declare module '@xds/lab/Thing' {\n  const y: number;\n}";
+    const output = await applyTransform(input);
+    expect(output).toMatch(/declare module ['"]@astryxdesign\/lab\/Thing['"]/);
+    expect(output).not.toContain('@xds/lab');
+  });
+
+  it('leaves non-xds declare modules alone', async () => {
+    const input = "declare module 'react' {\n  const z: number;\n}";
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('leaves an already-migrated declare module unchanged', async () => {
+    const input = "declare module '@astryxdesign/core/Heading' {\n  const a: number;\n}";
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch namespace declarations (Identifier id)', async () => {
+    const input = 'declare namespace XDSCore {\n  const b: number;\n}';
+    const output = await applyTransform(input, 'test.ts');
+    expect(output).toBe(input);
+  });
+});

package/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs

@@ -41,6 +41,29 @@ describe('v0.1.0 codemod manifest ordering', () => {
     expect(entry.optional).toBeFalsy();
   });
 
+  it('orders declare-module and CSS codemods after migrate-xds-module-specifiers', async () => {
+    const {default: manifest} = await import('../index.mjs');
+    const names = manifest.map(entry => entry.name);
+    expect(names).toEqual([
+      'drop-xds-prefix-imports',
+      'migrate-xds-module-specifiers',
+      'migrate-xds-declare-module',
+      'migrate-xds-css-surfaces',
+    ]);
+  });
+
+  it('marks migrate-xds-declare-module and migrate-xds-css-surfaces mandatory', async () => {
+    const {default: manifest} = await import('../index.mjs');
+    for (const name of [
+      'migrate-xds-declare-module',
+      'migrate-xds-css-surfaces',
+    ]) {
+      const entry = manifest.find(e => e.name === name);
+      expect(entry, name).toBeDefined();
+      expect(entry.optional).toBeFalsy();
+    }
+  });
+
   it('un-prefixes useXDSTheme from @xds/core/theme AND renames the scope to @astryxdesign', async () => {
     const input = [
       "import {useXDSTheme} from '@xds/core/theme';",

package/src/codemods/transforms/v0.1.0/index.mjs

@@ -14,6 +14,14 @@ import migrateXdsModuleSpecifiers, {
   meta as migrateXdsModuleSpecifiersMeta,
 } from './migrate-xds-module-specifiers.mjs';
 
+import migrateXdsDeclareModule, {
+  meta as migrateXdsDeclareModuleMeta,
+} from './migrate-xds-declare-module.mjs';
+
+import migrateXdsCssSurfaces, {
+  meta as migrateXdsCssSurfacesMeta,
+} from './migrate-xds-css-surfaces.mjs';
+
 export default [
   {
     // XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
@@ -34,4 +42,24 @@ export default [
     transform: migrateXdsModuleSpecifiers,
     meta: migrateXdsModuleSpecifiersMeta,
   },
+  {
+    // Cleans up TypeScript `declare module "@xds/core/..."` augmentations,
+    // which reference the package by string specifier and so are dead after
+    // the scope rename. Mandatory in v0.1.0. Ordered AFTER the specifier
+    // codemod: it uses the same @xds -> @astryxdesign mapping and repairs an
+    // adjacent surface the specifier codemod does not visit (module-decl ids
+    // are not import/export/require sources).
+    name: 'migrate-xds-declare-module',
+    transform: migrateXdsDeclareModule,
+    meta: migrateXdsDeclareModuleMeta,
+  },
+  {
+    // Rewrites consumer CSS surfaces broken by the v0.1.0 DOM-namespace rename
+    // (core no longer dual-emits `xds-*`): the `.xds-*` class-selector prefix,
+    // `[data-xds-*]` attribute selectors, and `@layer xds-*` layer names all
+    // become their `astryx-*` forms. Mandatory in v0.1.0.
+    name: 'migrate-xds-css-surfaces',
+    transform: migrateXdsCssSurfaces,
+    meta: migrateXdsCssSurfacesMeta,
+  },
 ];

package/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate XDS CSS surfaces to their Astryx equivalents
+ *
+ * The v0.1.0 release renamed the DOM namespace emitted by @astryxdesign/core
+ * from `xds-*` to `astryx-*` and dropped the dual-emit compatibility (core no
+ * longer emits the legacy `xds-*` classes or `data-xds-*` attributes). Any
+ * consumer CSS that targeted those surfaces is now broken.
+ *
+ * This transform performs precise, targeted string replacements on CSS/SCSS
+ * files for the documented surfaces only:
+ *
+ *   .xds-*                  (class-name prefix in selectors — matched only
+ *                            after a `.` so it is a class selector)
+ *   [data-xds-theme         (theme attribute selector)
+ *   [data-xds-theme-prose   (prose-theme attribute selector)
+ *   [data-xds-media         (media attribute selector)
+ *   @layer xds-theme        (cascade layer name — incl. comma-separated
+ *   @layer xds-base          `@layer a, b;` statement lists and nested blocks)
+ *
+ * It deliberately does NOT blindly replace every `xds` substring: a bare
+ * `xds` in a comment, a custom-property value, or an unrelated identifier is
+ * left untouched. CSS has no meaningful AST for this class of edit, so this is
+ * a plain string transform — `api.jscodeshift` is available but unused.
+ */
+
+export const meta = {
+  title: 'Migrate .xds-* / [data-xds-*] / @layer xds-* CSS surfaces to astryx',
+  description:
+    'Rewrites the documented XDS CSS surfaces to their Astryx equivalents: ' +
+    'the `.xds-*` class-selector prefix, `[data-xds-theme]` / ' +
+    '`[data-xds-theme-prose]` / `[data-xds-media]` attribute selectors, and ' +
+    '`@layer xds-theme` / `@layer xds-base` cascade-layer names all become ' +
+    'their `astryx-*` / `data-astryx-*` forms.',
+  pr: '#3092',
+  fileExtensions: ['.css', '.scss'],
+};
+
+// The XDS cascade-layer names we own. A `@layer` prelude can name several
+// layers in a comma-separated list (`@layer a, b;`), so we can't anchor every
+// occurrence to the `@layer` keyword. We instead rewrite these exact layer
+// tokens within a `@layer ...` prelude (up to the next `{` or `;`).
+const XDS_LAYER_NAMES = new Map([
+  ['xds-theme', 'astryx-theme'],
+  ['xds-base', 'astryx-base'],
+]);
+
+function rewriteLayerPrelude(prelude) {
+  return prelude.replace(/\bxds-(?:theme|base)\b/g, name =>
+    XDS_LAYER_NAMES.get(name) ?? name,
+  );
+}
+
+// Ordered, non-overlapping replacements. Each pattern is intentionally narrow
+// so we never touch a bare `xds` substring outside these surfaces.
+const REPLACEMENTS = [
+  // Class-name prefix: only when preceded by a `.` (a class selector).
+  {re: /\.xds-/g, to: '.astryx-'},
+  // Attribute selectors: any `[data-xds-` opener (theme, theme-prose, media).
+  {re: /\[data-xds-/g, to: '[data-astryx-'},
+  // Cascade-layer preludes: `@layer <names>` up to the block `{` or `;`.
+  // Rewrite only the recognized xds-* layer tokens inside the prelude.
+  {re: /@layer\b[^{;]*/g, to: match => rewriteLayerPrelude(match)},
+];
+
+export default function transformer(file /*, api */) {
+  const source = file.source;
+  if (typeof source !== 'string') return undefined;
+
+  let next = source;
+  for (const {re, to} of REPLACEMENTS) {
+    next = next.replace(re, to);
+  }
+
+  return next === source ? undefined : next;
+}