@specglass/theme-default 0.0.2 → 0.0.4

package/dist/__tests__/api-endpoint-fallback.test.d.ts

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

package/dist/__tests__/api-endpoint-fallback.test.js

@@ -0,0 +1,153 @@
+/**
+ * Tests for error endpoint slug generation, data contract, and
+ * the shared buildErrorEndpointSlug utility from @specglass/core.
+ */
+import { describe, it, expect } from "vitest";
+import { buildEndpointSlug, buildErrorEndpointSlug, buildEndpointId } from "@specglass/core";
+describe("buildErrorEndpointSlug", () => {
+    it("generates correct slug for a simple errored endpoint", () => {
+        const error = {
+            path: "/pets",
+            method: "get",
+            reason: "Complex polymorphism not supported",
+            rawSpec: { get: { summary: "List pets" } },
+        };
+        expect(buildErrorEndpointSlug(error)).toBe("_unsupported/get-pets");
+    });
+    it("generates correct slug for nested path with parameters", () => {
+        const error = {
+            path: "/users/{userId}/orders/{orderId}",
+            method: "patch",
+            reason: "Unsupported allOf/oneOf",
+            rawSpec: {},
+        };
+        expect(buildErrorEndpointSlug(error)).toBe("_unsupported/patch-users-userId-orders-orderId");
+    });
+    it("generates correct slug for root path", () => {
+        const error = {
+            path: "/",
+            method: "get",
+            reason: "Unsupported extension",
+            rawSpec: {},
+        };
+        expect(buildErrorEndpointSlug(error)).toBe("_unsupported/get-");
+    });
+    it("uses _unsupported prefix to avoid collision with valid endpoint slugs", () => {
+        // An errored endpoint at /pets GET should NOT collide with a valid
+        // endpoint at /pets GET (which gets slug "default/get-pets")
+        const error = {
+            path: "/pets",
+            method: "get",
+            reason: "test",
+            rawSpec: {},
+        };
+        const validEndpoint = {
+            path: "/pets",
+            method: "get",
+            tags: [],
+            summary: "",
+            description: "",
+            operationId: "",
+            deprecated: false,
+            parameters: [],
+            responses: [],
+            security: [],
+            requestBody: undefined,
+        };
+        const errorSlug = buildErrorEndpointSlug(error);
+        const validSlug = buildEndpointSlug(validEndpoint);
+        expect(errorSlug).not.toBe(validSlug);
+        expect(errorSlug).toContain("_unsupported/");
+        expect(validSlug).toContain("default/");
+    });
+    it("generates unique IDs for errored endpoints", () => {
+        const error = {
+            path: "/pets/{petId}",
+            method: "delete",
+            reason: "test",
+            rawSpec: {},
+        };
+        const errId = `${error.method}-${error.path}`;
+        expect(errId).toBe("delete-/pets/{petId}");
+        // This matches buildEndpointId behavior
+        const validEndpoint = {
+            path: "/pets/{petId}",
+            method: "delete",
+            tags: [],
+            summary: "",
+            description: "",
+            operationId: "",
+            deprecated: false,
+            parameters: [],
+            responses: [],
+            security: [],
+            requestBody: undefined,
+        };
+        expect(errId).toBe(buildEndpointId(validEndpoint));
+    });
+});
+describe("ApiEndpointError data contract", () => {
+    it("has all required fields for rendering", () => {
+        const error = {
+            path: "/complex-endpoint",
+            method: "post",
+            reason: "Complex polymorphism (allOf with discriminator) is not supported",
+            rawSpec: {
+                post: {
+                    summary: "Create complex resource",
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    allOf: [{ $ref: "#/components/schemas/Base" }],
+                                    discriminator: { propertyName: "type" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        // Verify all fields exist and are the correct types
+        expect(typeof error.path).toBe("string");
+        expect(typeof error.method).toBe("string");
+        expect(typeof error.reason).toBe("string");
+        expect(error.rawSpec).toBeDefined();
+        expect(typeof error.rawSpec).toBe("object");
+    });
+    it("rawSpec serializes to valid JSON for display", () => {
+        const error = {
+            path: "/test",
+            method: "get",
+            reason: "test",
+            rawSpec: {
+                nested: { deeply: { value: [1, 2, 3] } },
+                special: 'chars "in" strings',
+            },
+        };
+        const json = JSON.stringify(error.rawSpec, null, 2);
+        expect(() => JSON.parse(json)).not.toThrow();
+        expect(json).toContain("nested");
+        expect(json).toContain("deeply");
+    });
+    it("handles empty rawSpec gracefully", () => {
+        const error = {
+            path: "/test",
+            method: "get",
+            reason: "test",
+            rawSpec: {},
+        };
+        const json = JSON.stringify(error.rawSpec, null, 2);
+        expect(json).toBe("{}");
+    });
+    it("handles null rawSpec gracefully", () => {
+        const error = {
+            path: "/test",
+            method: "get",
+            reason: "test",
+            rawSpec: null,
+        };
+        const json = JSON.stringify(error.rawSpec, null, 2);
+        expect(json).toBe("null");
+    });
+});

package/dist/__tests__/code-tabs.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=code-tabs.test.d.ts.map

package/dist/__tests__/code-tabs.test.js

@@ -216,4 +216,3 @@ describe("CodeTabs", () => {
         });
     });
 });
-//# sourceMappingURL=code-tabs.test.js.map

package/dist/__tests__/copy-button.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=copy-button.test.d.ts.map

package/dist/__tests__/copy-button.test.js

@@ -113,4 +113,3 @@ describe("CopyButton logic", () => {
         expect(result.current.copied).toBe(false);
     });
 });
-//# sourceMappingURL=copy-button.test.js.map

package/dist/__tests__/search-palette.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=search-palette.test.d.ts.map

package/dist/__tests__/search-palette.test.js

@@ -68,4 +68,3 @@ describe("ui/dialog", () => {
         expect(mod.DialogDescription).toBeDefined();
     });
 });
-//# sourceMappingURL=search-palette.test.js.map

package/dist/__tests__/shiki.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=shiki.test.d.ts.map

package/dist/__tests__/shiki.test.js

@@ -34,4 +34,3 @@ describe("highlight utility", () => {
         expect(html2).toContain("--shiki-light");
     });
 });
-//# sourceMappingURL=shiki.test.js.map

package/dist/__tests__/theme-css.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=theme-css.test.d.ts.map

package/dist/__tests__/theme-css.test.js

@@ -121,4 +121,3 @@ describe("generateThemeCSS", () => {
         expect(css).not.toContain("--color-surface:");
     });
 });
-//# sourceMappingURL=theme-css.test.js.map

package/dist/__tests__/theme-helpers.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=theme-helpers.test.d.ts.map

package/dist/__tests__/theme-helpers.test.js

@@ -78,4 +78,3 @@ describe("theme-helpers", () => {
         });
     });
 });
-//# sourceMappingURL=theme-helpers.test.js.map

package/dist/index.d.ts

@@ -60,4 +60,3 @@ export interface TableOfContentsProps {
         text: string;
     }>;
 }
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -10,4 +10,3 @@ export { getStoredTheme, getEffectiveTheme, applyTheme, THEME_STORAGE_KEY, DEFAU
 export { ThemeToggle } from "./islands/ThemeToggle.js";
 export { CopyButton } from "./islands/CopyButton.js";
 export { CodeTabs } from "./islands/CodeTabs.js";
-//# sourceMappingURL=index.js.map

package/dist/islands/CodeTabs.d.ts

@@ -18,4 +18,3 @@ interface CodeTabsProps {
 declare function CodeTabs({ tabs, syncKey, ariaLabel }: CodeTabsProps): import("react/jsx-runtime").JSX.Element | null;
 export { CodeTabs };
 export type { CodeTab, CodeTabsProps };
-//# sourceMappingURL=CodeTabs.d.ts.map

package/dist/islands/CodeTabs.js

@@ -122,4 +122,3 @@ function CodeTabs({ tabs, syncKey = "sdk-language", ariaLabel = "SDK language ta
     return (_jsxs("div", { className: "my-6 border border-border rounded-lg overflow-hidden", children: [_jsx("div", { role: "tablist", "aria-label": ariaLabel, className: "flex border-b border-border bg-surface-raised", onKeyDown: handleKeyDown, children: tabs.map((tab, i) => (_jsx("button", { id: `${groupId}-tab-${i}`, role: "tab", "aria-selected": i === activeIndex, "aria-controls": `${groupId}-panel-${i}`, tabIndex: i === activeIndex ? 0 : -1, className: cn("px-4 py-2 border-b-2 border-transparent text-[0.8125rem] font-medium font-mono", "text-text-muted cursor-pointer whitespace-nowrap bg-transparent", "transition-colors duration-150 hover:text-text", "focus-visible:outline-2 focus-visible:outline-primary focus-visible:-outline-offset-2", i === activeIndex && "text-text border-b-primary"), onClick: () => setTab(i), children: tab.label }, tab.language))) }), tabs.map((tab, i) => (_jsx("div", { id: `${groupId}-panel-${i}`, role: "tabpanel", "aria-labelledby": `${groupId}-tab-${i}`, tabIndex: 0, className: "code-tabs-panel", style: { display: i === activeIndex ? undefined : "none" }, dangerouslySetInnerHTML: { __html: tab.content } }, tab.language)))] }));
 }
 export { CodeTabs };
-//# sourceMappingURL=CodeTabs.js.map

package/dist/islands/CopyButton.d.ts

@@ -13,4 +13,3 @@ export interface CopyButtonProps {
     code: string;
 }
 export declare function CopyButton({ code }: CopyButtonProps): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=CopyButton.d.ts.map

package/dist/islands/CopyButton.js

@@ -51,4 +51,3 @@ export function CopyButton({ code }) {
         /* Copy icon */
         _jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "9", y: "9", width: "13", height: "13", rx: "2", ry: "2" }), _jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })] })) }));
 }
-//# sourceMappingURL=CopyButton.js.map

package/dist/islands/SearchPalette.d.ts

@@ -1,2 +1 @@
 export declare function SearchPalette(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=SearchPalette.d.ts.map

package/dist/islands/SearchPalette.js

@@ -106,4 +106,3 @@ export function SearchPalette() {
                                                 __html: result.sub_results?.[0]?.excerpt ?? result.excerpt ?? "",
                                             } })] }, result.id)))] }), (results.length > 0 || query.trim().length > 0) && !isUnavailable && (_jsx("div", { className: "flex items-center justify-between border-t border-border px-3 py-2 text-xs text-text-muted", children: _jsxs("div", { className: "flex items-center gap-3", children: [_jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx("kbd", { className: "rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]", children: "\u2191\u2193" }), "navigate"] }), _jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx("kbd", { className: "rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]", children: "\u21B5" }), "open"] }), _jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx("kbd", { className: "rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]", children: "esc" }), "close"] })] }) }))] })] }));
 }
-//# sourceMappingURL=SearchPalette.js.map

package/dist/islands/SearchResults.d.ts

@@ -1,2 +1 @@
 export declare function SearchResults(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=SearchResults.d.ts.map

package/dist/islands/SearchResults.js

@@ -127,4 +127,3 @@ export function SearchResults() {
                                         __html: result.sub_results?.[0]?.excerpt ?? result.excerpt ?? "",
                                     } })] }, result.id)))] }))] }));
 }
-//# sourceMappingURL=SearchResults.js.map

package/dist/islands/ThemeToggle.d.ts

@@ -9,4 +9,3 @@
  * Imports shared utilities from theme-helpers.ts for consistency.
  */
 export declare function ThemeToggle(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=ThemeToggle.d.ts.map

package/dist/islands/ThemeToggle.js

@@ -40,4 +40,3 @@ export function ThemeToggle() {
     }, []);
     return (_jsx("button", { type: "button", onClick: toggleTheme, "aria-label": isDark ? "Switch to light mode" : "Switch to dark mode", className: "inline-flex items-center justify-center rounded-md p-2 text-text-muted hover:text-(--color-text) hover:bg-hover-bg focus:outline-none focus-visible:ring-2 focus-visible:ring-primary transition-colors", children: _jsxs("span", { className: "relative inline-flex items-center justify-center w-5 h-5", children: [_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", className: `absolute inset-0 transition-transform duration-300 ${isDark ? "rotate-0 scale-100" : "-rotate-90 scale-0"}`, children: [_jsx("circle", { cx: "12", cy: "12", r: "4" }), _jsx("path", { d: "M12 2v2" }), _jsx("path", { d: "M12 20v2" }), _jsx("path", { d: "m4.93 4.93 1.41 1.41" }), _jsx("path", { d: "m17.66 17.66 1.41 1.41" }), _jsx("path", { d: "M2 12h2" }), _jsx("path", { d: "M20 12h2" }), _jsx("path", { d: "m6.34 17.66-1.41 1.41" }), _jsx("path", { d: "m19.07 4.93-1.41 1.41" })] }), _jsx("svg", { xmlns: "http://www.w3.org/2000/svg", width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", className: `absolute inset-0 transition-transform duration-300 ${!isDark ? "rotate-0 scale-100" : "rotate-90 scale-0"}`, children: _jsx("path", { d: "M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" }) })] }) }));
 }
-//# sourceMappingURL=ThemeToggle.js.map

package/dist/layouts/DocPage.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=DocPage.test.d.ts.map

package/dist/layouts/DocPage.test.js

@@ -162,4 +162,3 @@ describe("DocPage props contract", () => {
         });
     });
 });
-//# sourceMappingURL=DocPage.test.js.map

package/dist/lib/utils.d.ts

@@ -7,4 +7,3 @@ import { type ClassValue } from "clsx";
  * Will be used by UI primitives in upcoming stories (e.g., search, dialogs).
  */
 export declare function cn(...inputs: ClassValue[]): string;
-//# sourceMappingURL=utils.d.ts.map

package/dist/lib/utils.js

@@ -10,4 +10,3 @@ import { twMerge } from "tailwind-merge";
 export function cn(...inputs) {
     return twMerge(clsx(inputs));
 }
-//# sourceMappingURL=utils.js.map

package/dist/scripts/code-block-enhancer.d.ts

@@ -13,4 +13,3 @@
  * until the user actually clicks copy.
  */
 declare function initCopyButtons(): void;
-//# sourceMappingURL=code-block-enhancer.d.ts.map

package/dist/scripts/code-block-enhancer.js

@@ -52,4 +52,3 @@ function initCopyButtons() {
 document.addEventListener("DOMContentLoaded", initCopyButtons);
 // Re-run after Astro ViewTransitions page swaps
 document.addEventListener("astro:after-swap", initCopyButtons);
-//# sourceMappingURL=code-block-enhancer.js.map

package/dist/ui/command.d.ts

@@ -84,4 +84,3 @@ declare const CommandShortcut: {
     displayName: string;
 };
 export { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator, };
-//# sourceMappingURL=command.d.ts.map

package/dist/ui/command.js

@@ -25,4 +25,3 @@ const CommandShortcut = ({ className, ...props }) => {
 };
 CommandShortcut.displayName = "CommandShortcut";
 export { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator, };
-//# sourceMappingURL=command.js.map

package/dist/ui/dialog.d.ts

@@ -17,4 +17,3 @@ declare const DialogFooter: {
 declare const DialogTitle: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
 declare const DialogDescription: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
 export { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };
-//# sourceMappingURL=dialog.d.ts.map

package/dist/ui/dialog.js

@@ -19,4 +19,3 @@ DialogTitle.displayName = DialogPrimitive.Title.displayName;
 const DialogDescription = React.forwardRef(({ className, ...props }, ref) => (_jsx(DialogPrimitive.Description, { ref: ref, className: cn("text-sm text-text-muted", className), ...props })));
 DialogDescription.displayName = DialogPrimitive.Description.displayName;
 export { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };
-//# sourceMappingURL=dialog.js.map

package/dist/utils/parse-highlight-range.d.ts

@@ -9,4 +9,3 @@
  * parseHighlightRange("") // → []
  */
 export declare function parseHighlightRange(range: string): number[];
-//# sourceMappingURL=parse-highlight-range.d.ts.map

package/dist/utils/parse-highlight-range.js

@@ -37,4 +37,3 @@ export function parseHighlightRange(range) {
     }
     return result;
 }
-//# sourceMappingURL=parse-highlight-range.js.map

package/dist/utils/parse-highlight-range.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=parse-highlight-range.test.d.ts.map

package/dist/utils/parse-highlight-range.test.js

@@ -29,4 +29,3 @@ describe("parseHighlightRange", () => {
         expect(parseHighlightRange("1,abc,3")).toEqual([1, 3]);
     });
 });
-//# sourceMappingURL=parse-highlight-range.test.js.map

package/dist/utils/schema-renderer.d.ts

@@ -35,4 +35,3 @@ export declare function renderTypeString(schema: ApiSchema | undefined): string;
  * suitable for rendering in a table. Only expands 1 level deep for MVP.
  */
 export declare function flattenSchemaProperties(schema: ApiSchema | undefined, requiredFields?: string[], maxDepth?: number): SchemaProperty[];
-//# sourceMappingURL=schema-renderer.d.ts.map

package/dist/utils/schema-renderer.js

@@ -112,4 +112,3 @@ export function flattenSchemaProperties(schema, requiredFields, maxDepth = 1) {
     }
     return properties;
 }
-//# sourceMappingURL=schema-renderer.js.map

package/dist/utils/schema-renderer.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=schema-renderer.test.d.ts.map

package/dist/utils/schema-renderer.test.js

@@ -216,4 +216,3 @@ describe("flattenSchemaProperties", () => {
         expect(props[0].name).toBe("nested");
     });
 });
-//# sourceMappingURL=schema-renderer.test.js.map

package/dist/utils/shiki.d.ts

@@ -17,4 +17,3 @@ export interface HighlightOptions {
  * Returns raw HTML string with CSS variable tokens — ready for `set:html`.
  */
 export declare function highlight(code: string, lang: string, options?: HighlightOptions): Promise<string>;
-//# sourceMappingURL=shiki.d.ts.map

package/dist/utils/shiki.js

@@ -81,4 +81,3 @@ export async function highlight(code, lang, options) {
         ...(decorations?.length ? { decorations } : {}),
     });
 }
-//# sourceMappingURL=shiki.js.map

package/dist/utils/sidebar-helpers.d.ts

@@ -7,4 +7,3 @@ import type { NavItem } from "@specglass/core";
 export declare function filterVisibleItems(items: NavItem[]): NavItem[];
 /** Check if this item or any descendant is the current page. */
 export declare function isActiveOrAncestor(item: NavItem, currentSlug: string): boolean;
-//# sourceMappingURL=sidebar-helpers.d.ts.map

package/dist/utils/sidebar-helpers.js

@@ -11,4 +11,3 @@ export function isActiveOrAncestor(item, currentSlug) {
     }
     return false;
 }
-//# sourceMappingURL=sidebar-helpers.js.map

package/dist/utils/theme-css.d.ts

@@ -18,4 +18,3 @@ import type { SpecglassConfig } from "@specglass/core";
  * ```
  */
 export declare function generateThemeCSS(config: SpecglassConfig): string;
-//# sourceMappingURL=theme-css.d.ts.map

package/dist/utils/theme-css.js

@@ -74,4 +74,3 @@ export function generateThemeCSS(config) {
         return "";
     return `:root {\n${overrides.join("\n")}\n}`;
 }
-//# sourceMappingURL=theme-css.js.map

package/dist/utils/theme-helpers.d.ts

@@ -25,4 +25,3 @@ export declare function getEffectiveTheme(stored: Theme | null): Theme;
  * Also persists the preference to localStorage.
  */
 export declare function applyTheme(theme: Theme): void;
-//# sourceMappingURL=theme-helpers.d.ts.map

package/dist/utils/theme-helpers.js

@@ -52,4 +52,3 @@ export function applyTheme(theme) {
         // localStorage unavailable — graceful degradation
     }
 }
-//# sourceMappingURL=theme-helpers.js.map

package/dist/utils/toc-helpers.d.ts

@@ -9,4 +9,3 @@ export type Heading = {
 };
 /** Filter headings to include only h2 and h3 for ToC display. */
 export declare function filterTocHeadings(headings: Heading[]): Heading[];
-//# sourceMappingURL=toc-helpers.d.ts.map

package/dist/utils/toc-helpers.js

@@ -6,4 +6,3 @@
 export function filterTocHeadings(headings) {
     return headings.filter((h) => h.depth >= 2 && h.depth <= 3);
 }
-//# sourceMappingURL=toc-helpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specglass/theme-default",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Default theme for Specglass — layouts, components, React islands, and styles",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,9 @@
     "./layouts/*": "./src/layouts/*",
     "./lib/*": "./src/lib/*",
     "./styles/*": "./src/styles/*",
-    "./utils/*": "./src/utils/*"
+    "./utils/*": "./src/utils/*",
+    "./ui/*": "./src/ui/*",
+    "./scripts/*": "./src/scripts/*"
   },
   "files": [
     "dist",
@@ -32,7 +34,9 @@
     "src/layouts",
     "src/lib",
     "src/styles",
-    "src/utils"
+    "src/utils",
+    "src/ui",
+    "src/scripts"
   ],
   "scripts": {
     "build": "tsc",

package/src/components/ApiEndpointFallback.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * ApiEndpointFallback.astro — Renders a "Manual Documentation Required" placeholder
+ * for endpoints where the OpenAPI parser encountered unsupported spec patterns (FR40).
+ *
+ * Shows the error reason and raw spec data in a collapsible, syntax-highlighted block.
+ */
+import type { ApiEndpointError } from "@specglass/core";
+import { CopyButton } from "../islands/CopyButton";
+import { highlight } from "../utils/shiki";
+
+export interface Props {
+  error: ApiEndpointError;
+}
+
+const { error } = Astro.props;
+
+const methodColors: Record<string, string> = {
+  get: "bg-emerald-500/15 text-emerald-700 dark:text-emerald-400 border-emerald-500/30",
+  post: "bg-blue-500/15 text-blue-700 dark:text-blue-400 border-blue-500/30",
+  put: "bg-amber-500/15 text-amber-700 dark:text-amber-400 border-amber-500/30",
+  patch: "bg-yellow-500/15 text-yellow-700 dark:text-yellow-400 border-yellow-500/30",
+  delete: "bg-red-500/15 text-red-700 dark:text-red-400 border-red-500/30",
+  options: "bg-purple-500/15 text-purple-700 dark:text-purple-400 border-purple-500/30",
+  head: "bg-gray-500/15 text-gray-700 dark:text-gray-400 border-gray-500/30",
+};
+
+const methodColor = methodColors[error.method.toLowerCase()] ?? methodColors.get;
+const rawSpecJson = JSON.stringify(error.rawSpec, null, 2);
+const highlightedSpec = await highlight(rawSpecJson, "json");
+---
+
+<div id={`endpoint-${error.method}-${error.path.replace(/[{}\\\/]/g, "-")}`} class="mb-8">
+  {/* Method + Path header */}
+  <div class="flex items-center gap-3 mb-4">
+    <span
+      class:list={[
+        "inline-flex items-center px-3 py-1 rounded-full text-xs font-bold uppercase tracking-wider border",
+        methodColor,
+      ]}
+    >
+      {error.method.toUpperCase()}
+    </span>
+    <code class="text-lg font-mono text-text font-semibold break-all">
+      {error.path}
+    </code>
+  </div>
+
+  {/* Warning alert */}
+  <div
+    role="alert"
+    class="rounded-lg border border-amber-500/30 bg-amber-50 dark:bg-amber-950/20 px-5 py-4 mb-6"
+  >
+    <div class="flex items-start gap-3">
+      <span class="text-amber-600 dark:text-amber-400 text-xl mt-0.5" aria-hidden="true">⚠️</span>
+      <div>
+        <h3 class="text-base font-semibold text-amber-800 dark:text-amber-200 mt-0 mb-1">
+          Manual Documentation Required
+        </h3>
+        <p class="text-sm text-amber-700 dark:text-amber-300 leading-relaxed m-0">
+          This endpoint uses an OpenAPI spec pattern that couldn't be fully parsed.
+          {
+            error.reason && (
+              <span class="block mt-1 text-amber-600 dark:text-amber-400 font-medium">
+                {error.reason}
+              </span>
+            )
+          }
+        </p>
+      </div>
+    </div>
+  </div>
+
+  {/* Raw spec data — collapsed by default */}
+  <details class="rounded-lg border border-border bg-surface-code overflow-hidden">
+    <summary
+      class="cursor-pointer px-4 py-3 text-sm font-medium text-text-muted hover:text-text transition-colors select-none flex items-center gap-2"
+    >
+      <svg
+        class="w-4 h-4 transition-transform open:rotate-90"
+        viewBox="0 0 20 20"
+        fill="currentColor"
+        aria-hidden="true"
+      >
+        <path
+          fill-rule="evenodd"
+          d="M7.21 14.77a.75.75 0 01.02-1.06L11.168 10 7.23 6.29a.75.75 0 111.04-1.08l4.5 4.25a.75.75 0 010 1.08l-4.5 4.25a.75.75 0 01-1.06-.02z"
+          clip-rule="evenodd"></path>
+      </svg>
+      View raw OpenAPI spec data
+    </summary>
+    <div class="relative group border-t border-border">
+      <div
+        class="[&_pre]:overflow-x-auto [&_pre]:p-4 [&_pre]:text-sm [&_pre]:leading-relaxed [&_pre]:m-0"
+        set:html={highlightedSpec}
+      />
+      <div class="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity">
+        <CopyButton client:idle code={rawSpecJson} />
+      </div>
+    </div>
+  </details>
+</div>