@djangocfg/ui-tools 2.1.289 → 2.1.290

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.289",
+  "version": "2.1.290",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -90,8 +90,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.289",
-    "@djangocfg/ui-core": "^2.1.289",
+    "@djangocfg/i18n": "^2.1.290",
+    "@djangocfg/ui-core": "^2.1.290",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -101,30 +101,34 @@
     "zustand": "^5.0.0"
   },
   "dependencies": {
-    "@tiptap/core": "^3.20.1",
-    "@tiptap/react": "^3.20.1",
-    "@tiptap/starter-kit": "^3.20.1",
-    "@tiptap/extension-placeholder": "^3.20.1",
-    "@tiptap/extension-mention": "^3.20.1",
-    "@tiptap/suggestion": "^3.20.1",
-    "@tiptap/markdown": "^3.20.1",
-    "@tiptap/pm": "^3.20.1",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
     "@rpldy/uploady": "^1.8.5",
+    "@tiptap/core": "^3.20.1",
+    "@tiptap/extension-mention": "^3.20.1",
+    "@tiptap/extension-placeholder": "^3.20.1",
+    "@tiptap/markdown": "^3.20.1",
+    "@tiptap/pm": "^3.20.1",
+    "@tiptap/react": "^3.20.1",
+    "@tiptap/starter-kit": "^3.20.1",
+    "@tiptap/suggestion": "^3.20.1",
     "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
     "maplibre-gl": "^4.7.1",
     "media-icons": "next",
     "mermaid": "^11.12.0",
     "monaco-editor": "^0.55.1",
+    "openapi-sampler": "^1.7.2",
     "prism-react-renderer": "^2.4.1",
+    "prismjs": "^1.30.0",
     "react-json-tree": "^0.20.0",
     "react-lottie-player": "^2.1.0",
     "react-map-gl": "^8.1.0",
     "react-markdown": "10.1.0",
     "react-zoom-pan-pinch": "^3.7.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
     "remark-gfm": "4.0.1",
     "vidstack": "next",
     "wavesurfer.js": "^7.12.1"
@@ -134,10 +138,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.289",
+    "@djangocfg/i18n": "^2.1.290",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.289",
-    "@djangocfg/ui-core": "^2.1.289",
+    "@djangocfg/typescript-config": "^2.1.290",
+    "@djangocfg/ui-core": "^2.1.290",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/components/markdown/MarkdownMessage.tsx

@@ -2,8 +2,37 @@
 
 import React from 'react';
 import ReactMarkdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
 import remarkGfm from 'remark-gfm';
 
+// Allow-list HTML that OpenAPI descriptions commonly use — we want
+// ``<b>``/``<code>``/``<br>`` to render, not to appear as literal text.
+// Built on top of ``rehype-sanitize``'s default schema so we keep the
+// XSS protection (no ``<script>``, no ``on*`` handlers, no ``javascript:``
+// URLs); we just extend the tag allow-list with safe presentational
+// elements that are in wide use in API docs.
+const HTML_SCHEMA = {
+  ...defaultSchema,
+  tagNames: [
+    ...(defaultSchema.tagNames ?? []),
+    'br',
+    'b',
+    'i',
+    'u',
+    's',
+    'sub',
+    'sup',
+    'small',
+    'mark',
+    'kbd',
+    'code',
+    'pre',
+    'details',
+    'summary',
+  ],
+};
+
 import { CopyButton } from '@djangocfg/ui-core/components';
 import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
 
@@ -331,6 +360,16 @@ const hasMarkdownSyntax = (text: string): boolean => {
     return true;
   }
 
+  // Inline HTML tags (``<br>``, ``<b>``, ``<code>``, …) — used widely
+  // in OpenAPI descriptions. Without this branch the plain-text fast
+  // path would escape them and the user sees literal angle brackets.
+  // The regex matches opening, closing, and self-closing tags without
+  // being too clever about malformed HTML; it's an affordance test,
+  // not a validator.
+  if (/<\/?[a-zA-Z][a-zA-Z0-9-]*(\s[^>]*)?\/?>/.test(text)) {
+    return true;
+  }
+
   // Common markdown patterns
   const markdownPatterns = [
     /^#{1,6}\s/m,           // Headers
@@ -549,6 +588,13 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
       >
         <ReactMarkdown
           remarkPlugins={[remarkGfm]}
+          // ``rehype-raw`` parses inline HTML in the source (OpenAPI
+          // ``description`` fields often contain ``<br>`` / ``<b>`` /
+          // ``<code>``). ``rehype-sanitize`` with our extended schema
+          // runs after it so the allowed tags pass through while
+          // anything risky (scripts, event handlers, javascript: urls)
+          // is stripped.
+          rehypePlugins={[rehypeRaw, [rehypeSanitize, HTML_SCHEMA]]}
           components={components}
         >
           {displayContent}

package/src/tools/OpenapiViewer/OpenapiViewer.story.tsx

@@ -1,4 +1,4 @@
-import { defineStory, useSelect, useValue } from '@djangocfg/playground';
+import { defineStory, useSelect, useValue, useBoolean } from '@djangocfg/playground';
 import { Playground } from './index';
 import { LazyOpenapiViewer } from './lazy';
 import type { PlaygroundConfig } from './types';
@@ -11,13 +11,18 @@ export default defineStory({
 });
 
 // ============================================================================
-// Schema configs
+// Schema fixtures
 // ============================================================================
 
+// Petstore's own ``servers[0].url`` is just ``/api/v3`` (relative),
+// which makes code samples look like they target ``localhost`` when
+// viewed from the playground. Override with the canonical public host
+// so the generated curl/fetch/etc snippets are runnable as-is.
 const PETSTORE_SCHEMA = {
   id: 'petstore',
   name: 'Petstore API',
   url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+  baseUrl: 'https://petstore3.swagger.io/api/v3',
 } as const;
 
 const HTTPBIN_SCHEMA = {
@@ -28,15 +33,18 @@ const HTTPBIN_SCHEMA = {
 
 const MULTI_SCHEMAS = [PETSTORE_SCHEMA, HTTPBIN_SCHEMA] as const;
 
-// Simulates a real multi-group setup (like cmdop with 5+ API groups)
+// Simulates a real multi-group setup (like cmdop with 5+ API groups).
+// All clones share the canonical Petstore host so code samples
+// render with a real runnable URL.
+const PETSTORE_BASE = 'https://petstore3.swagger.io/api/v3';
 const MANY_SCHEMAS = [
   PETSTORE_SCHEMA,
   HTTPBIN_SCHEMA,
-  { id: 'machines', name: 'Machines API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'terminal', name: 'Terminal API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'skills', name: 'Skills API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'system', name: 'System API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'site', name: 'Site API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
+  { id: 'machines', name: 'Machines API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'terminal', name: 'Terminal API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'skills', name: 'Skills API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'system', name: 'System API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'site', name: 'Site API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
 ] as const;
 
 // ============================================================================
@@ -44,60 +52,34 @@ const MANY_SCHEMAS = [
 // ============================================================================
 
 /**
- * Interactive — default schema is adjustable.
+ * Default — single-schema mode with the most common configuration knobs
+ * exposed as toggles. Replaces the earlier Interactive / SingleSchema /
+ * WithBaseUrl / NoDefault / CustomUrl stories, which were all "this
+ * component with different props" variations.
  */
-export const Interactive = () => {
-  const [defaultSchema] = useSelect('defaultSchema', {
-    options: ['petstore', 'httpbin'] as const,
-    defaultValue: 'petstore',
-    label: 'Default Schema',
-    description: 'Which schema to load first',
+export const Default = () => {
+  const [schemaUrl] = useValue('schemaUrl', {
+    defaultValue: PETSTORE_SCHEMA.url,
+    label: 'Schema URL',
+    description: 'Any OpenAPI 3.x JSON endpoint',
   });
 
-  const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
-    defaultSchemaId: defaultSchema,
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * With baseUrl override — forces a specific request host, ignoring
- * `schema.servers[0].url`. Useful when docs are hosted on a different
- * origin than the API, or when the schema has no servers entry.
- */
-export const WithBaseUrl = () => {
   const [baseUrl] = useValue('baseUrl', {
-    defaultValue: 'https://petstore3.swagger.io/api/v3',
-    label: 'Base URL',
-    description: 'Overrides schema.servers[0].url for every request',
+    defaultValue: '',
+    label: 'Base URL override',
+    description: 'Empty = use servers[0].url from the schema',
   });
 
-  const config: PlaygroundConfig = {
-    schemas: [PETSTORE_SCHEMA],
-    defaultSchemaId: 'petstore',
-    baseUrl,
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
+  const [autoSelect] = useBoolean('autoSelectDefault', {
+    defaultValue: true,
+    label: 'Auto-select default schema',
+    description: 'When off, tests the "no defaultSchemaId" code path',
+  });
 
-/**
- * Single schema — no Combobox switcher shown (schemas.length === 1).
- */
-export const SingleSchema = () => {
   const config: PlaygroundConfig = {
-    schemas: [PETSTORE_SCHEMA],
-    defaultSchemaId: 'petstore',
+    schemas: [{ id: 'custom', name: 'Schema', url: schemaUrl }],
+    defaultSchemaId: autoSelect ? 'custom' : undefined,
+    baseUrl: baseUrl || undefined,
   };
 
   return (
@@ -108,12 +90,20 @@ export const SingleSchema = () => {
 };
 
 /**
- * Multiple schemas with Combobox switcher.
- * Switch between Petstore and HTTPBin to see different endpoint sets.
+ * MultiSchema — multiple schemas with the Combobox switcher. Count
+ * is adjustable to exercise both the short-list layout and the
+ * long-list behaviour (cmdop-style setups with 7+ APIs).
  */
-export const MultipleSchemas = () => {
+export const MultiSchema = () => {
+  const [count] = useSelect('count', {
+    options: ['2', '7'] as const,
+    defaultValue: '2',
+    label: 'Schema count',
+    description: '2 uses Petstore+HTTPBin; 7 stress-tests the Combobox',
+  });
+
   const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
+    schemas: count === '2' ? [...MULTI_SCHEMAS] : [...MANY_SCHEMAS],
     defaultSchemaId: 'petstore',
   };
 
@@ -125,14 +115,14 @@ export const MultipleSchemas = () => {
 };
 
 /**
- * Sections grouping — all schemas rendered as top-level headings in the
- * sidebar, with every endpoint laid out on the same page. URL hash sync
- * is enabled so scrolling updates ``#<schemaId>/<anchor>``.
+ * SectionsGrouping — alternate layout: every schema's endpoints get
+ * rendered on the same page as top-level sections, with a sidebar
+ * that stacks them. URL hash sync writes ``#<schemaId>/<anchor>``
+ * as the user scrolls so deep-linking keeps working.
  */
 export const SectionsGrouping = () => {
-  const [urlSync] = useSelect('urlSync', {
-    options: ['on', 'off'] as const,
-    defaultValue: 'on',
+  const [urlSync] = useBoolean('urlSync', {
+    defaultValue: true,
     label: 'URL hash sync',
     description: 'Writes #<schemaId>/<anchor> as you scroll',
   });
@@ -141,7 +131,7 @@ export const SectionsGrouping = () => {
     schemas: [...MULTI_SCHEMAS],
     defaultSchemaId: 'petstore',
     schemaGrouping: 'sections',
-    urlSync: urlSync === 'on',
+    urlSync,
   };
 
   return (
@@ -152,91 +142,37 @@ export const SectionsGrouping = () => {
 };
 
 /**
- * Many schemas (7+) — tests Combobox with a long list.
- * Simulates a real setup like cmdop with machines, terminal, skills, etc.
+ * Errors — consolidated failure paths. Pick a scenario via the toggle:
+ *   - ``broken``: single schema that 404s → full-panel error state.
+ *   - ``mixed``: valid + broken side-by-side → tests switching between.
+ *   - ``empty``: no schemas configured at all → empty-state UI.
  */
-export const ManySchemas = () => {
-  const config: PlaygroundConfig = {
-    schemas: [...MANY_SCHEMAS],
-    defaultSchemaId: 'petstore',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * No defaultSchemaId — should auto-select the first schema.
- */
-export const NoDefault = () => {
-  const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * Error state — invalid schema URL that will fail to fetch.
- * Tests error handling and UI feedback.
- */
-export const ErrorState = () => {
-  const config: PlaygroundConfig = {
-    schemas: [
-      {
-        id: 'broken',
-        name: 'Broken API',
-        url: 'https://httpbin.org/status/404',
-      },
-    ],
-    defaultSchemaId: 'broken',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * Mixed valid + broken — one schema works, one fails.
- * Tests switching between working and broken schemas.
- */
-export const MixedValidBroken = () => {
-  const config: PlaygroundConfig = {
-    schemas: [
-      PETSTORE_SCHEMA,
-      {
-        id: 'broken',
-        name: 'Broken API (404)',
-        url: 'https://httpbin.org/status/404',
-      },
-    ],
-    defaultSchemaId: 'petstore',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
+export const Errors = () => {
+  const [scenario] = useSelect('scenario', {
+    options: ['broken', 'mixed', 'empty'] as const,
+    defaultValue: 'broken',
+    label: 'Failure scenario',
+  });
 
-/**
- * Empty schemas array — edge case, no schemas provided.
- */
-export const EmptySchemas = () => {
-  const config: PlaygroundConfig = {
-    schemas: [],
-  };
+  const config: PlaygroundConfig = (() => {
+    switch (scenario) {
+      case 'broken':
+        return {
+          schemas: [{ id: 'broken', name: 'Broken API', url: 'https://httpbin.org/status/404' }],
+          defaultSchemaId: 'broken',
+        };
+      case 'mixed':
+        return {
+          schemas: [
+            PETSTORE_SCHEMA,
+            { id: 'broken', name: 'Broken API (404)', url: 'https://httpbin.org/status/404' },
+          ],
+          defaultSchemaId: 'petstore',
+        };
+      case 'empty':
+        return { schemas: [] };
+    }
+  })();
 
   return (
     <div className="min-h-[600px]">
@@ -246,8 +182,9 @@ export const EmptySchemas = () => {
 };
 
 /**
- * LazyOpenapiViewer — the production lazy-loaded variant.
- * Shows loading spinner while ~400KB of OpenAPI components load.
+ * Lazy — production lazy-loaded variant. Shows the loading spinner
+ * while the ~400 KB OpenAPI viewer chunk is fetched. Only path you
+ * should use in an actual app bundle.
  */
 export const Lazy = () => {
   const config: PlaygroundConfig = {
@@ -261,31 +198,3 @@ export const Lazy = () => {
     </div>
   );
 };
-
-/**
- * Custom schema URL — paste any OpenAPI 3.x schema URL to test.
- */
-export const CustomUrl = () => {
-  const [url] = useValue('schemaUrl', {
-    defaultValue: 'https://petstore3.swagger.io/api/v3/openapi.json',
-    label: 'Schema URL',
-    description: 'Full URL to an OpenAPI 3.x JSON schema',
-  });
-
-  const config: PlaygroundConfig = {
-    schemas: [
-      {
-        id: 'custom',
-        name: 'Custom Schema',
-        url,
-      },
-    ],
-    defaultSchemaId: 'custom',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};

package/src/tools/OpenapiViewer/README.md

@@ -101,6 +101,9 @@ OpenapiViewer/
 ├── utils/
 │   ├── url.ts                   # UrlBuilder + path/query/baseUrl helpers
 │   ├── schemaExport.ts          # Dereferenced/compact/markdown export for LLMs
+│   ├── sampler.ts               # Schema → example value (openapi-sampler wrap)
+│   ├── operationToHar.ts        # ApiEndpoint → HAR request shape
+│   ├── codeSamples.ts           # HAR → curl / fetch / python / … renderers
 │   ├── formatters.ts            # HTTP status / method helpers, JSON validation
 │   ├── versionManager.ts
 │   ├── apiKeyManager.ts
@@ -110,28 +113,126 @@ OpenapiViewer/
     ├── index.ts                 # Re-exports DocsLayout
     ├── DocsLayout/              # Default (only) layout
     │   ├── index.tsx            # Root: sidebar + docs + slide-in playground
-    │   ├── Sidebar.tsx          # Grouped endpoint list, scrollspy highlight
     │   ├── DocsView.tsx         # Longread scroll container + scrollspy
-    │   ├── EndpointDoc.tsx      # One endpoint as a prose section + fields table
     │   ├── ApiIntroSection.tsx  # Top intro + Copy-for-AI dropdown
     │   ├── SchemaCopyMenu.tsx   # Per-schema copy flavours
     │   ├── SlideInPlayground.tsx# Right slide-in overlay
     │   ├── TryItSheet.tsx       # Mobile/tablet fallback via ResponsiveSheet
     │   ├── anchor.ts            # Stable section anchors for deep-linking
     │   ├── grouping.ts          # Shared group+sort used by sidebar and docs
-    │   ├── schemaFields.ts      # JSON Schema → flat field rows
-    │   └── sidebarLabel.ts      # Common-prefix strip + tooltip helpers
+    │   ├── schemaFields.ts      # JSON Schema → flat field rows (legacy helper)
+    │   ├── sidebarLabel.ts      # Common-prefix strip + tooltip helpers
+    │   │
+    │   ├── Sidebar/             # Grouped endpoint list + toolbar
+    │   │   ├── index.tsx        # Orchestrator
+    │   │   ├── types.ts         # VM types + METHOD_FILTERS
+    │   │   ├── buildVM.ts       # Pure view-model builders (flat + sections)
+    │   │   ├── useDebouncedValue.ts
+    │   │   ├── BrandHeader.tsx  # Title + version + Copy-for-AI
+    │   │   ├── Toolbar.tsx      # Schema combobox + search + method chips
+    │   │   ├── SearchInput.tsx
+    │   │   ├── MethodChips.tsx
+    │   │   ├── SidebarBody.tsx  # flat vs sections switch
+    │   │   ├── SchemaSection.tsx
+    │   │   ├── CategoryBlock.tsx
+    │   │   └── EndpointRow.tsx
+    │   │
+    │   └── EndpointDoc/         # One endpoint as a prose card
+    │       ├── index.tsx        # Orchestrator: header + sections
+    │       ├── types.ts         # SectionId union
+    │       ├── context.tsx      # Identity context (endpointId + method)
+    │       │
+    │       ├── store/           # Zustand — open sections + active code tab
+    │       │   ├── index.ts     # create() + sessionStorage persist
+    │       │   └── selectors.ts
+    │       │
+    │       ├── hooks/
+    │       │   └── useSectionHash.ts  # #section=<id>.<sec> deep-link router
+    │       │
+    │       ├── Header/          # Meta row (badge + actions + Try it) + path
+    │       │   ├── index.tsx
+    │       │   ├── MetaActions.tsx    # Copy link / markdown / expand all
+    │       │   ├── MethodBadge.tsx
+    │       │   └── PathDisplay.tsx
+    │       │
+    │       ├── Section/         # Collapsible section wrapper
+    │       │   ├── index.tsx
+    │       │   ├── SectionHeader.tsx  # Chevron + title + badge + anchor
+    │       │   └── defaults.ts        # Per-method open-by-default rules
+    │       │
+    │       ├── Parameters/      # Path + Query parameters block
+    │       │   ├── index.tsx
+    │       │   ├── ParamGroup.tsx
+    │       │   └── ParamRow.tsx
+    │       │
+    │       ├── RequestBody/     # Body preview
+    │       │   └── index.tsx
+    │       │
+    │       ├── SchemaFields/    # Tree-view of JSON Schema properties
+    │       │   ├── index.tsx
+    │       │   ├── FieldRow.tsx
+    │       │   ├── buildTree.ts
+    │       │   └── types.ts
+    │       │
+    │       ├── Responses/       # Status-code rows + example body
+    │       │   ├── index.tsx
+    │       │   ├── ResponseRow.tsx
+    │       │   ├── ResponseBody.tsx
+    │       │   └── StatusTag.tsx
+    │       │
+    │       └── CodeSamples/     # Language tabs + generated snippet
+    │           ├── index.tsx
+    │           ├── LanguageTabs.tsx
+    │           └── useCodeSnippet.ts
     │
     └── shared/                  # Panels reused by SlideInPlayground + TryItSheet
         ├── RequestPanel.tsx
-        ├── ResponsePanel.tsx
         ├── SendButton.tsx
         ├── BodyFormEditor.tsx   # Recursive JSON-Schema form renderer
         ├── EndpointDraftSync.tsx# Headless draft ↔ context sync
         ├── EndpointResetButton.tsx
-        └── ui.tsx               # MethodBadge, StatusBadge, Panel, atoms
+        ├── ui.tsx               # MethodBadge, StatusBadge, Panel, atoms
+        │
+        └── ResponsePanel/       # Response viewer with Pretty / Raw / Preview tabs
+            ├── index.tsx        # Orchestrator + mode state + guards
+            ├── types.ts         # ViewMode + ContentKind
+            ├── detectContent.ts # Content-Type → Prism language inference
+            ├── useResponseView.ts
+            ├── StatusBar.tsx    # Status / size / duration / Copy
+            ├── ViewTabs.tsx
+            ├── PrettyView.tsx   # JsonTree or syntax-highlighted code
+            ├── RawView.tsx      # Plain <pre>
+            └── PreviewView.tsx  # Sandboxed iframe for HTML responses
 ```
 
+## Endpoint doc — sections & deep-linking
+
+Each endpoint card splits into four collapsible sections: **Parameters**,
+**Request body**, **Code samples**, **Responses**. Defaults are
+method-aware — GET opens Parameters + Responses, POST/PUT/PATCH opens
+Request body + Responses, etc. User overrides are persisted per
+endpoint in `sessionStorage` (zustand `persist` middleware) so a tab you
+opened once stays open as you scroll.
+
+A hover-revealed anchor button on each section header copies a shareable
+URL like `…#section=ep-get-api-v3-pet-findbystatus.responses` —
+following that link lands on the endpoint, expands the referenced
+section, and scrolls it into view.
+
+## Response panel — Pretty / Raw / Preview
+
+The response panel picks a default view based on `Content-Type`:
+
+- **JSON** → `Pretty` (interactive JsonTree)
+- **HTML** → `Preview` (sandboxed iframe, scripts disabled) with `Pretty`
+  as the syntax-highlighted source fallback
+- **XML / CSS / JS / text** → `Pretty` using Prism
+- Everything has a **Raw** tab for a literal `<pre>` dump
+
+The HTML preview detects single-page-app shells (empty `<body>` + mount
+div + `<script>`) and shows an explanatory empty-state instead of a
+blank iframe, since scripts can't run in the sandbox.
+
 ## Config Reference
 
 ```ts
@@ -145,6 +246,13 @@ interface PlaygroundConfig {
   /** Optional API keys for the X-API-Key picker. */
   apiKeys?: ApiKey[];
   apiKeysLoading?: boolean;
+  /** Layout mode. ``'selector'`` (default) shows one schema at a time,
+   *  picked via a Combobox. ``'sections'`` flattens every schema into
+   *  the longread as top-level sections. */
+  schemaGrouping?: 'selector' | 'sections';
+  /** Sync the active endpoint anchor to ``window.location.hash`` as
+   *  the user scrolls (sections mode). Default: off. */
+  urlSync?: boolean;
 }
 
 interface SchemaSource {