@writedocs/generator 0.1.0

package/src/lib/openapi-render.ts

@@ -0,0 +1,479 @@
+// Rendering helpers for ApiPlayground.astro - mostly pure functions over
+// an already-dereferenced OpenAPI operation (as written by
+// src/cli/generate-api-pages.js to writedocsTempDir()'s
+// openapi/<path>/operations/*.json), kept separate from the
+// .astro component so the schema-walking logic (which has nothing to do
+// with markup) is easy to read and test on its own. findOperationFile()
+// below is the one exception (it touches the filesystem) - kept here
+// anyway since it's used by exactly the same two consumers as
+// operationFileName(), right next to it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+
+export interface OpenApiSchema {
+  type?: string;
+  properties?: Record<string, OpenApiSchema>;
+  items?: OpenApiSchema;
+  required?: string[];
+  allOf?: OpenApiSchema[];
+  oneOf?: OpenApiSchema[];
+  anyOf?: OpenApiSchema[];
+  enum?: unknown[];
+  example?: unknown;
+  default?: unknown;
+  description?: string;
+  format?: string;
+  nullable?: boolean;
+}
+
+export interface OpenApiParameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  required?: boolean;
+  description?: string;
+  schema?: OpenApiSchema;
+  example?: unknown;
+}
+
+/** Mirrors operationFileName() in src/cli/generate-api-pages.js exactly -
+ *  the pre-step wrote each operation's resolved JSON under
+ *  writedocsTempDir()'s openapi/<path>/operations/ directory using this same naming scheme,
+ *  so both ApiPlayground.astro and ApiReferencePanel.astro (which
+ *  independently read that file rather than sharing one parsed value
+ *  passed through props) need to compute the identical filename. */
+export function operationFileName(method: string, urlPath: string): string {
+  return `${method.toLowerCase()}_${urlPath.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')}.json`;
+}
+
+/** Locates a single operation's resolved JSON under writedocsTempDir()'s
+ *  openapi/<path>/operations/ directory - one such directory exists per
+ *  openapi group in writedocs.json (see generate-api-pages.js), each
+ *  namespaced under that group's own `path`, so a page's `openapi:
+ *  "METHOD /path"` frontmatter alone doesn't say which one to look in.
+ *  Rather than threading a spec identifier through every page's
+ *  frontmatter just for this lookup, this walks the (small - one
+ *  directory per spec) openapi/ tree once per call, checking
+ *  every "operations" directory it finds for the target filename. Returns
+ *  null if no group's spec defines this operation (a stale/typo'd
+ *  `openapi:` frontmatter value). */
+export function findOperationFile(contentDir: string, method: string, urlPath: string): string | null {
+  const openapiRoot = path.join(writedocsTempDir(contentDir), 'openapi');
+  const filename = operationFileName(method, urlPath);
+
+  function walk(dir: string): string | null {
+    if (!fs.existsSync(dir)) return null;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'operations') {
+        const candidate = path.join(full, filename);
+        if (fs.existsSync(candidate)) return candidate;
+        continue; // an "operations" dir has no further subdirectories worth descending into
+      }
+      const found = walk(full);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  return walk(openapiRoot);
+}
+
+// A single named entry in a media-type object's `examples` map (OpenAPI's
+// plural, named form - distinct from the singular `example` a schema or
+// media-type object can also carry, already handled separately via
+// exampleFromSchema()). Each key is the example's own name (not
+// necessarily human-readable - `summary` is what a UI should actually
+// display, falling back to the key itself when absent).
+export interface OpenApiExample {
+  summary?: string;
+  description?: string;
+  value?: unknown;
+}
+
+export interface OpenApiOperation {
+  method: string;
+  path: string;
+  operationId: string | null;
+  summary: string | null;
+  description: string | null;
+  tags: string[];
+  parameters: OpenApiParameter[];
+  requestBody: {
+    required?: boolean;
+    content?: Record<string, { schema?: OpenApiSchema; examples?: Record<string, OpenApiExample> }>;
+  } | null;
+  responses: Record<string, { description?: string; content?: Record<string, { schema?: OpenApiSchema }> }>;
+  servers: { url: string }[];
+  security: { name: string; type: string; in?: string; scheme?: string }[];
+}
+
+/** Merges `allOf` members into one flat {type, properties, required}
+ *  shape - dereferencing (done once, up front, by generate-api-pages.js)
+ *  resolves $ref pointers but doesn't collapse schema *composition*, so
+ *  this still needs to happen at render time. `oneOf`/`anyOf` aren't
+ *  merged (that would be misleading - they're alternatives, not a
+ *  combination) - the first variant is shown, which covers the common
+ *  case of "one of several near-identical response shapes" well enough
+ *  for a reference view without building a full variant switcher. */
+export function resolveSchema(schema: OpenApiSchema | undefined): OpenApiSchema {
+  if (!schema) return {};
+  if (schema.allOf) {
+    return schema.allOf.reduce<OpenApiSchema>(
+      (acc, member) => {
+        const resolved = resolveSchema(member);
+        return {
+          ...acc,
+          ...resolved,
+          properties: { ...acc.properties, ...resolved.properties },
+          required: [...(acc.required ?? []), ...(resolved.required ?? [])],
+        };
+      },
+      { type: 'object', properties: {}, required: [] }
+    );
+  }
+  if (schema.oneOf?.[0]) return resolveSchema(schema.oneOf[0]);
+  if (schema.anyOf?.[0]) return resolveSchema(schema.anyOf[0]);
+  return schema;
+}
+
+function typeLabel(schema: OpenApiSchema): string {
+  const resolved = resolveSchema(schema);
+  if (resolved.type === 'array') return `${typeLabel(resolved.items ?? {})}[]`;
+  if (resolved.enum) return resolved.enum.map((v) => JSON.stringify(v)).join(' | ');
+  return resolved.format ? `${resolved.type}<${resolved.format}>` : (resolved.type ?? 'any');
+}
+
+export interface SchemaRow {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string | null;
+  // A nested object's (or array-of-objects') own properties, one level
+  // down - empty for anything that bottoms out at a plain value. Used by
+  // ApiSchemaField.astro to decide whether a row needs an <Expandable>
+  // wrapping a recursive render of itself, rather than a flat
+  // depth-indented row (an earlier version of this returned one flat,
+  // pre-flattened array with a `depth` number instead - replaced once
+  // the reference design called for a real collapsible "Show/Hide
+  // properties" control per nested object, the same one already used for
+  // hand-written Parameter/Expandable content elsewhere on API pages,
+  // rather than everything permanently expanded and indented). */
+  children: SchemaRow[];
+}
+
+/** Builds a *tree* of an object schema's properties, one SchemaRow per
+ *  property with its own nested object/array-of-objects properties (if
+ *  any) attached as `children` rather than flattened alongside it -
+ *  ApiSchemaField.astro walks this recursively, rendering each level of
+ *  `children` inside its own <Expandable>. Arrays of objects recurse into
+ *  the array's own item schema (same as a plain nested object - the
+ *  distinction between "one nested object" and "an array of them" isn't
+ *  meaningful for *which properties* exist, only for `type`'s own label,
+ *  see typeLabel() above); everything else bottoms out with an empty
+ *  `children` array. */
+export function schemaRows(schema: OpenApiSchema | undefined): SchemaRow[] {
+  const resolved = resolveSchema(schema);
+  const target = resolved.type === 'array' ? resolveSchema(resolved.items) : resolved;
+  if (!target.properties) return [];
+  const required = new Set(target.required ?? []);
+  return Object.entries(target.properties).map(([name, propSchema]) => {
+    const resolvedProp = resolveSchema(propSchema);
+    const children =
+      resolvedProp.type === 'object' || resolvedProp.type === 'array' ? schemaRows(propSchema) : [];
+    return {
+      name,
+      type: typeLabel(propSchema),
+      required: required.has(name),
+      description: propSchema.description ?? null,
+      children,
+    };
+  });
+}
+
+/** Builds a plausible example value for a schema - `example`/`default`
+ *  win outright when present (most specs that care about this provide
+ *  one), otherwise a type-appropriate placeholder is synthesized so the
+ *  "Try it" body textarea and the static example block are never just
+ *  empty for a schema that didn't bother to include examples. */
+export function exampleFromSchema(schema: OpenApiSchema | undefined, depth = 0): unknown {
+  if (!schema) return null;
+  if (schema.example !== undefined) return schema.example;
+  if (schema.default !== undefined) return schema.default;
+  if (schema.enum?.[0] !== undefined) return schema.enum[0];
+  if (depth > 6) return null; // guard against a pathological/self-referential schema
+
+  const resolved = resolveSchema(schema);
+  if (resolved.type === 'object' || resolved.properties) {
+    const out: Record<string, unknown> = {};
+    for (const [name, propSchema] of Object.entries(resolved.properties ?? {})) {
+      out[name] = exampleFromSchema(propSchema, depth + 1);
+    }
+    return out;
+  }
+  if (resolved.type === 'array') return [exampleFromSchema(resolved.items, depth + 1)];
+  if (resolved.type === 'integer' || resolved.type === 'number') return 0;
+  if (resolved.type === 'boolean') return true;
+  if (resolved.type === 'string') {
+    if (resolved.format === 'date-time') return new Date(0).toISOString();
+    if (resolved.format === 'date') return '2024-01-01';
+    if (resolved.format === 'email') return 'user@example.com';
+    if (resolved.format === 'uuid') return '00000000-0000-0000-0000-000000000000';
+    return 'string';
+  }
+  return null;
+}
+
+/** Same object/array shape-walking as exampleFromSchema, but every leaf
+ *  is left blank instead of filled with a synthesized placeholder - the
+ *  Try-it modal's "Default" example option uses this (rather than an
+ *  empty textarea) so the reader still sees exactly which fields the
+ *  request body needs and can fill each one in, instead of losing the
+ *  shape entirely. Strings are '' (their own native "nothing yet"),
+ *  arrays are [] (no item to show without a real example), and
+ *  numbers/booleans are null - 0/false would themselves look like
+ *  real, deliberately-chosen values rather than an unfilled field. */
+export function emptyValueFromSchema(schema: OpenApiSchema | undefined, depth = 0): unknown {
+  if (!schema) return null;
+  if (depth > 6) return null; // guard against a pathological/self-referential schema
+
+  const resolved = resolveSchema(schema);
+  if (resolved.type === 'object' || resolved.properties) {
+    const out: Record<string, unknown> = {};
+    for (const [name, propSchema] of Object.entries(resolved.properties ?? {})) {
+      out[name] = emptyValueFromSchema(propSchema, depth + 1);
+    }
+    return out;
+  }
+  if (resolved.type === 'array') return [];
+  if (resolved.type === 'string') return '';
+  return null;
+}
+
+/** The single content-type this operation's request body is rendered
+ *  for - application/json when available (by far the common case for
+ *  anything with a playground worth building), else whatever the spec
+ *  happens to list first. */
+export function primaryContentType(
+  content: Record<string, { schema?: OpenApiSchema }> | undefined
+): string | null {
+  if (!content) return null;
+  if ('application/json' in content) return 'application/json';
+  return Object.keys(content)[0] ?? null;
+}
+
+const METHOD_COLORS: Record<string, string> = {
+  GET: 'get',
+  POST: 'post',
+  PUT: 'put',
+  PATCH: 'patch',
+  DELETE: 'delete',
+};
+
+export function methodClass(method: string): string {
+  return METHOD_COLORS[method.toUpperCase()] ?? 'other';
+}
+
+/** Splits "/pets/{petId}" into alternating literal/param segments, so the
+ *  path can be rendered with `{param}` portions visually distinguished
+ *  from the literal path structure around them. */
+export function pathSegments(urlPath: string): { text: string; isParam: boolean }[] {
+  const parts = urlPath.split(/(\{[^}]+\})/g).filter((p) => p !== '');
+  return parts.map((text) => ({ text, isParam: /^\{.*\}$/.test(text) }));
+}
+
+function jsonBody(schema: OpenApiSchema | undefined): string | null {
+  if (!schema) return null;
+  return JSON.stringify(exampleFromSchema(schema), null, 2);
+}
+
+export function buildCurlSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const headerParams = op.parameters.filter((p) => p.in === 'header');
+  const queryParams = op.parameters.filter((p) => p.in === 'query');
+  const url =
+    baseUrl.replace(/\/$/, '') +
+    op.path.replace(/\{(\w+)\}/g, (_, name) => `<${name}>`) +
+    (queryParams.length > 0 ? '?' + queryParams.map((p) => `${p.name}=<${p.name}>`).join('&') : '');
+
+  const lines = [`curl -X ${op.method} "${url}" \\`];
+  if (contentType) lines.push(`  -H "Content-Type: ${contentType}" \\`);
+  for (const h of headerParams) lines.push(`  -H "${h.name}: <${h.name}>" \\`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') lines.push(`  -H "${s.name}: <${s.name}>" \\`);
+    if (s.type === 'http' && s.scheme === 'bearer') lines.push(`  -H "Authorization: Bearer <token>" \\`);
+    if (s.type === 'http' && s.scheme === 'basic') lines.push(`  -u "<username>:<password>" \\`);
+  }
+  if (body) lines.push(`  -d '${body}'`);
+  const last = lines[lines.length - 1];
+  lines[lines.length - 1] = last.endsWith('\\') ? last.slice(0, -2) : last;
+  return lines.join('\n');
+}
+
+export function buildFetchSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `\${${name}}`);
+  const headers: string[] = [];
+  if (contentType) headers.push(`'Content-Type': '${contentType}'`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`'${s.name}': '<${s.name}>'`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`'Authorization': 'Bearer <token>'`);
+  }
+  const optsLines = [`method: '${op.method}'`, headers.length ? `headers: { ${headers.join(', ')} }` : null, body ? `body: JSON.stringify(${body})` : null].filter(Boolean);
+  return `const response = await fetch(\`${url}\`, {\n  ${optsLines.join(',\n  ')}\n});\nconst data = await response.json();`;
+}
+
+export function buildPythonSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `{${name}}`);
+  const headers: string[] = [];
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`"${s.name}": "<${s.name}>"`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`"Authorization": "Bearer <token>"`);
+  }
+  const lines = ['import requests', '', `response = requests.request(`, `    "${op.method}",`, `    "${url}",`];
+  if (headers.length) lines.push(`    headers={ ${headers.join(', ')} },`);
+  if (body) lines.push(`    json=${body.replace(/\btrue\b/g, 'True').replace(/\bfalse\b/g, 'False').replace(/\bnull\b/g, 'None')},`);
+  lines.push(')', 'data = response.json()');
+  return lines.join('\n');
+}
+
+// The four snippet builders below follow buildFetchSnippet/
+// buildPythonSnippet's own subset of buildCurlSnippet's behavior, not
+// buildCurlSnippet's full one - only apiKey-in-header and bearer
+// security get a placeholder header, no query params get appended to
+// the URL, and no basic-auth handling - since that's the precedent
+// already set by every other non-curl snippet on this page, matching it
+// keeps all seven tabs behaviorally consistent with each other rather
+// than curl alone being the odd one out with extra capability the rest
+// quietly lack.
+export function buildPhpSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `<${name}>`);
+  const headers: string[] = [];
+  if (contentType) headers.push(`"Content-Type: ${contentType}"`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`"${s.name}: <${s.name}>"`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`"Authorization: Bearer <token>"`);
+  }
+  const lines = [
+    '$ch = curl_init();',
+    `curl_setopt($ch, CURLOPT_URL, "${url}");`,
+    'curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);',
+    `curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "${op.method}");`,
+  ];
+  if (headers.length) lines.push(`curl_setopt($ch, CURLOPT_HTTPHEADER, [${headers.join(', ')}]);`);
+  if (body) lines.push(`curl_setopt($ch, CURLOPT_POSTFIELDS, '${body}');`);
+  lines.push('$response = curl_exec($ch);', 'curl_close($ch);');
+  return `<?php\n${lines.join('\n')}`;
+}
+
+export function buildGoSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `<${name}>`);
+  const headers: string[] = [];
+  if (contentType) headers.push(`req.Header.Set("Content-Type", "${contentType}")`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`req.Header.Set("${s.name}", "<${s.name}>")`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`req.Header.Set("Authorization", "Bearer <token>")`);
+  }
+  const bodyExpr = body ? `strings.NewReader(\`${body}\`)` : 'nil';
+  const lines = [
+    'package main',
+    '',
+    'import (',
+    '\t"fmt"',
+    '\t"io"',
+    '\t"net/http"',
+    ...(body ? ['\t"strings"'] : []),
+    ')',
+    '',
+    'func main() {',
+    `\treq, _ := http.NewRequest("${op.method}", "${url}", ${bodyExpr})`,
+    ...headers.map((h) => `\t${h}`),
+    '',
+    '\tresp, err := http.DefaultClient.Do(req)',
+    '\tif err != nil {',
+    '\t\tpanic(err)',
+    '\t}',
+    '\tdefer resp.Body.Close()',
+    '',
+    '\tdata, _ := io.ReadAll(resp.Body)',
+    '\tfmt.Println(string(data))',
+    '}',
+  ];
+  return lines.join('\n');
+}
+
+export function buildJavaSnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `<${name}>`);
+  const headers: string[] = [];
+  if (contentType) headers.push(`.header("Content-Type", "${contentType}")`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`.header("${s.name}", "<${s.name}>")`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`.header("Authorization", "Bearer <token>")`);
+  }
+  // JSON.stringify's escaping (quotes, backslashes, newlines) happens to
+  // double as a valid Java string-literal escape too, so this reuses it
+  // rather than hand-rolling a second escaper just for this language.
+  const bodyPublisher = body
+    ? `HttpRequest.BodyPublishers.ofString(${JSON.stringify(body)})`
+    : 'HttpRequest.BodyPublishers.noBody()';
+  const lines = [
+    'HttpClient client = HttpClient.newHttpClient();',
+    'HttpRequest request = HttpRequest.newBuilder()',
+    `    .uri(URI.create("${url}"))`,
+    ...headers.map((h) => `    ${h}`),
+    `    .method("${op.method}", ${bodyPublisher})`,
+    '    .build();',
+    '',
+    'HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());',
+    'System.out.println(response.body());',
+  ];
+  return lines.join('\n');
+}
+
+export function buildRubySnippet(op: OpenApiOperation, baseUrl: string): string {
+  const contentType = primaryContentType(op.requestBody?.content);
+  const bodySchema = contentType ? op.requestBody?.content?.[contentType]?.schema : undefined;
+  const body = jsonBody(bodySchema);
+  const url = baseUrl.replace(/\/$/, '') + op.path.replace(/\{(\w+)\}/g, (_, name) => `<${name}>`);
+  const methodClass = op.method.charAt(0).toUpperCase() + op.method.slice(1).toLowerCase();
+  const headers: string[] = [];
+  if (contentType) headers.push(`request["Content-Type"] = "${contentType}"`);
+  for (const s of op.security) {
+    if (s.type === 'apiKey' && s.in === 'header') headers.push(`request["${s.name}"] = "<${s.name}>"`);
+    if (s.type === 'http' && s.scheme === 'bearer') headers.push(`request["Authorization"] = "Bearer <token>"`);
+  }
+  const lines = [
+    'require "net/http"',
+    'require "uri"',
+    '',
+    `uri = URI("${url}")`,
+    'http = Net::HTTP.new(uri.host, uri.port)',
+    'http.use_ssl = uri.scheme == "https"',
+    '',
+    `request = Net::HTTP::${methodClass}.new(uri)`,
+    ...headers,
+    ...(body ? [`request.body = ${JSON.stringify(body)}`] : []),
+    '',
+    'response = http.request(request)',
+    'puts response.body',
+  ];
+  return lines.join('\n');
+}

package/src/lib/shiki-code-block.js

@@ -0,0 +1,102 @@
+// A single combined Shiki transformer covering everything about a
+// fenced (```) code block's outer chrome that isn't syntax coloring
+// itself: wrapping every block in a positioned `.wd-code-block`
+// container, injecting the copy-to-clipboard button, and reading a
+// handful of writedocs-specific meta flags off the fence's info string
+// (the part after the language, e.g. ```js title="foo.js" wrap lines
+// expandable) to add a title bar and toggle wrap/line-numbers/
+// expandable behavior. Registered in astro.config.mjs's
+// markdown.shikiConfig.transformers, alongside the official
+// @shikijs/transformers notation/meta-highlight transformers that
+// handle the actual line/word annotation classes.
+//
+// Everything here only produces static HAST/HTML at build time - the
+// click behavior for the copy and expand/collapse buttons lives in
+// [...slug].astro's client script instead, and the CSS for all of this
+// (including the classes the @shikijs/transformers transformers add)
+// lives there too.
+//
+// Deliberately NOT used by ApiPlayground/ApiReferencePanel's <Code/>
+// usages - per Astro's docs, <Code/> doesn't inherit markdown.shikiConfig
+// at all, so this only ever touches genuine ```-fenced MDX content and
+// never collides with the API playground's own bespoke copy buttons.
+
+const META_TITLE_RE = /title\s*=\s*(["'])((?:(?!\1).)*)\1/;
+
+function parseMeta(raw) {
+  return {
+    title: raw.match(META_TITLE_RE)?.[2] ?? null,
+    wrap: /\bwrap\b/.test(raw),
+    lines: /\b(?:lines|showLineNumbers)\b/.test(raw),
+    expandable: /\bexpandable\b/.test(raw),
+  };
+}
+
+export function codeBlockTransformer() {
+  return {
+    name: 'writedocs:code-block',
+    // Runs once per block, before `root` - stashes the parsed meta
+    // flags on `this` (the shared per-block transformer context; see
+    // @shikijs/core's tokensToHast, which calls both `pre` and `root`
+    // with the same `context` object for a given block, but a *fresh*
+    // one for each block) so `root` below doesn't have to re-parse it.
+    pre(node) {
+      this.wdMeta = parseMeta(this.options.meta?.__raw ?? '');
+      return node;
+    },
+    root(hast) {
+      const pre = hast.children.find((child) => child.type === 'element' && child.tagName === 'pre');
+      if (!pre) return hast;
+      const meta = this.wdMeta ?? parseMeta(this.options.meta?.__raw ?? '');
+
+      const wrapperClass = ['wd-code-block'];
+      if (meta.wrap) wrapperClass.push('wd-code-wrap');
+      if (meta.lines) wrapperClass.push('wd-code-lines');
+      if (meta.expandable) wrapperClass.push('wd-code-expandable');
+
+      const children = [];
+      if (meta.title) {
+        children.push({
+          type: 'element',
+          tagName: 'div',
+          properties: { class: 'wd-code-title' },
+          children: [{ type: 'text', value: meta.title }],
+        });
+      }
+      children.push(pre);
+      children.push({
+        type: 'element',
+        tagName: 'button',
+        properties: {
+          type: 'button',
+          class: 'wd-code-copy-btn',
+          'data-role': 'copy-code',
+          'aria-label': 'Copy code',
+        },
+        children: [{ type: 'text', value: '⧉' }],
+      });
+      if (meta.expandable) {
+        children.push({
+          type: 'element',
+          tagName: 'button',
+          properties: {
+            type: 'button',
+            class: 'wd-code-expand-btn',
+            'data-role': 'toggle-expand',
+          },
+          children: [{ type: 'text', value: 'Show more' }],
+        });
+      }
+
+      hast.children = [
+        {
+          type: 'element',
+          tagName: 'div',
+          properties: { class: wrapperClass.join(' ') },
+          children,
+        },
+      ];
+      return hast;
+    },
+  };
+}

package/src/lib/shiki-copy-button.js

@@ -0,0 +1,45 @@
+// A Shiki transformer that wraps every fenced (```) code block's <pre>
+// in a positioned container and injects a copy-to-clipboard button next
+// to it - registered in astro.config.mjs's markdown.shikiConfig so it
+// runs for every MDX code fence sitewide. The click handling (clipboard
+// write, "copied" feedback) lives in [...slug].astro's own client
+// script instead of here, since a Shiki transformer only ever produces
+// static HAST/HTML at build time and has no way to attach behavior.
+//
+// Deliberately NOT used by ApiPlayground/ApiReferencePanel's <Code/>
+// usages - per Astro's docs, <Code/> doesn't inherit markdown.shikiConfig
+// at all, so this only ever touches genuine ```-fenced MDX content and
+// never collides with the API playground's own bespoke copy buttons
+// (which copy whichever language tab is currently visible, not "the
+// whole block").
+export function copyButtonTransformer() {
+  return {
+    name: 'writedocs:copy-button',
+    root(hast) {
+      const pre = hast.children.find((child) => child.type === 'element' && child.tagName === 'pre');
+      if (!pre) return hast;
+      hast.children = [
+        {
+          type: 'element',
+          tagName: 'div',
+          properties: { class: 'wd-code-block' },
+          children: [
+            pre,
+            {
+              type: 'element',
+              tagName: 'button',
+              properties: {
+                type: 'button',
+                class: 'wd-code-copy-btn',
+                'data-role': 'copy-code',
+                'aria-label': 'Copy code',
+              },
+              children: [{ type: 'text', value: '⧉' }],
+            },
+          ],
+        },
+      ];
+      return hast;
+    },
+  };
+}