rapidoc 12.0.0 → 12.1.0

package/README.md

@@ -59,39 +59,52 @@ Include the script in your HTML page and use the `<rapi-doc>` custom element:
 
 ## Repository Architecture
 
-This repository is structured as a **Monorepo** using workspaces, compatible with **Node/npm**, **pnpm**, and **Bun**:
+This repository is a monorepo built on **npm workspaces** (`packages/*` and `docs`):
 
 ```text
 rapidoc/
 ├── packages/
-│   ├── rapidoc/                 # Core Web Component library (published as "rapidoc")
-│   │   ├── src/                 # Web component source code (Lit + modern ESM)
-│   │   ├── dist/                # Production bundle (rapidoc-min.js)
-│   │   ├── package.json         # Library package config
-│   │   └── vite.config.mjs      # Dedicated library build config
+│   ├── rapidoc/                 # Core web component library (npm "rapidoc"): <rapi-doc>, <rapi-doc-mini>
+│   │   ├── src/                 # Lit 3 source; each folder has a README.md contract
+│   │   ├── dist/                # rapidoc-min.js and rapidoc-flow-min.js ("rapidoc/flow"), both for browsers
+│   │   ├── vite.config.mjs      # Browser bundle build
+│   │   └── vite.config.flow.mjs # <rapi-flow> bundle build
 │   │
-│   ├── rapidoc-cli/             # The `rapidoc` command (init, dev, build, validate, migrate)
-│   │   ├── src/                 # CLI source code
-│   │   └── package.json
+│   ├── rapidoc-prerender/       # @rapidoc/prerender: build-time renderer (pre-rendered <rapi-doc>, sidebar HTML) for Node
+│   ├── rapidoc-mcp/             # @rapidoc/mcp: MCP manifest builder, runtime and project writer for Node
 │   │
-│   └── rapidoc-portal/          # PocketBase developer portal to host & secure specs
-│       └── package.json
+│   ├── rapidoc-cli/             # @rapidoc/cli, the `rapidoc` command: init, dev, build, serve, mock, validate, migrate
+│   ├── rapidoc-portal/          # @rapidoc/portal: docs-as-code developer portal for OpenAPI and Markdoc (Astro)
+│   ├── rapidoc-server/          # @rapidoc/server: serves a built portal with OpenID Connect sign-in and access rules
+│   ├── rapidoc-mock/            # @rapidoc/mock: mock server for a portal's APIs, with OAuth scope checks
+│   └── create-rapidoc/          # create-rapidoc: scaffolds a new portal (npm create rapidoc)
 │
-├── docs/                        # Astro documentation & showcase site (GitHub Pages)
-│   ├── src/                     # Astro pages, components, and layouts
-│   │   ├── pages/examples/      # Public showcase pages (code-highlight, petstore, etc.)
-│   │   └── pages/tests/         # Internal test & edge-case pages
+├── docs/                        # Astro + Starlight documentation and showcase site (GitHub Pages)
+│   ├── src/
+│   │   ├── content/docs/        # Documentation pages
+│   │   ├── pages/examples/      # Public showcase pages
+│   │   ├── pages/tests/         # Internal test and edge-case pages
+│   │   └── page-data/           # YAML data for attribute tables and the example list
 │   ├── public/
-│   │   ├── specs/               # PUBLIC showcase specs (used by /examples)
-│   │   └── specs-test/          # INTERNAL test specs (edge cases & parser fixtures)
-│   │       └── parser/          # Malformed & validation test specs
-│   ├── astro.config.mjs         # Astro site configuration
-│   └── package.json             # Workspace package "docs"
+│   │   ├── specs/               # Public showcase specs (used by /examples)
+│   │   └── specs-test/          # Internal edge-case specs
+│   │       └── parser/          # Malformed and invalid specs for validation tests
+│   ├── generated-docs/          # Committed build of the site; the docs build refreshes only its rapidoc-min.js
+│   └── astro.config.mjs         # Astro site configuration
 │
-├── tests/
-│   └── visual/                  # Automated visual regression test suite (Playwright)
+├── tests/                       # See tests/README.md
+│   ├── unit/                    # Node test runner: parser, schema, templates, static renderer
+│   ├── component/               # Lit component tests
+│   ├── e2e/                     # Functional tests in a headless browser (playwright-core)
+│   ├── perf/                    # Spec parsing and rendering benchmarks
+│   ├── fixtures/                # Shared specs and the HTML test harness
+│   └── helpers/                 # Test server and browser helpers
 │
-├── package.json                 # Monorepo root configuration (workspaces)
+├── scripts/                     # Build info capture, demo prerender, test loader
+├── docker/                      # Dockerfile and Nginx config for hosting RapiDoc
+├── brand/                       # Logo SVGs and usage notes
+├── package.json                 # Monorepo root: npm workspaces (packages/*, docs) and scripts
+├── AGENTS.md                    # Guidance for contributors and coding agents
 └── README.md
 ```
 
@@ -246,7 +259,7 @@ When code is pushed to `master` or `main`, the [deploy-docs.yml](file:///Users/m
 
 OpenAPI specs are organized inside `docs/public/` based on their visibility and purpose:
 
-- **`docs/public/specs/`**: Public showcase specs referenced in [example-list.yaml](file:///Users/mrin/work/rapidoc/docs/src/data/example-list.yaml) and displayed on `rapidocui.com` (e.g., `petstore.yaml`, `code-highlight.yaml`, `auth.yaml`).
+- **`docs/public/specs/`**: Public showcase specs referenced in `docs/src/page-data/example-list.yaml` and displayed on `rapidocui.com` (e.g., `petstore.yaml`, `code-highlight.yaml`, `auth.yaml`).
 - **`docs/public/specs-test/`**: Internal edge-case and boundary specs used for UI verification and regression tests (e.g., `circular-refs.yaml`, `xxx-of-combinations.yaml`).
 - **`docs/public/specs-test/parser/`**: Malformed or invalid specs used to test CLI validation and error reporting (e.g., `invalid-syntax.yaml`, `missing-info.yaml`, `broken-ref.yaml`).
 
@@ -257,12 +270,101 @@ OpenAPI specs are organized inside `docs/public/` based on their visibility and
 - [x] Modernize project dependencies (Vite + Astro + Node 22+)
 - [x] Restructure as a multi-package Monorepo
 - [ ] Build `rapidoc-cli` for OpenAPI linting and local zero-config previews
-- [ ] Build `rapidoc-portal` with PocketBase for developer API portals
+- [x] Build `rapidoc-portal`, a docs-as-code developer portal, with sign-in (`rapidoc-server`) and mocking (`rapidoc-mock`)
 - [ ] Automated visual regression testing suite with Playwright
 - [ ] Web Content Accessibility Guidelines (WCAG 2.1) compliance enhancements
 
 ---
 
+## Architecture Contract
+
+What this package exposes, what must stay true, and what touches the outside world. Each folder
+under `src/` has its own `README.md` contract with the detail; this section covers the package as
+a whole.
+
+### Overview
+
+`packages/rapidoc` is a Lit 3 web component library built by Vite into two ES module bundles. It
+has no runtime dependencies: its libraries are `devDependencies` bundled into those files. Each
+build writes `dist/<bundle>.LICENSE.txt`, the list of bundled packages with their versions and
+license notices, and the bundle's banner names it:
+
+- `dist/rapidoc-min.js` (`vite.config.mjs`, entry `src/index.js`): registers `<rapi-doc>`,
+  `<rapi-doc-mini>` and `<oauth-receiver>` on import. Production builds are minified, carry the
+  license banner, and have `console.*` and `debugger` removed.
+- `dist/rapidoc-flow-min.js` (`vite.config.flow.mjs`, entry `src/flow.js`), exported as
+  `rapidoc/flow`: registers `<rapi-flow>`, the Arazzo workflow diagram, with the workflow runtime
+  that runs them in the browser. It bundles its own copy of Lit and `yaml`, so pages that do not
+  load it pay nothing; `rapidoc-min.js` carries no Arazzo runtime.
+
+Two Node packages are built from this source: `@rapidoc/prerender` (`packages/rapidoc-prerender`), the
+build-time renderer that renders these templates and components to HTML, and `@rapidoc/mcp`
+(`packages/rapidoc-mcp`), the MCP code in `src/utils/` (`mcp-generator.js`, `mcp/`, `arazzo/`).
+Nothing in `src/` imports either package.
+
+```text
+spec-url / inline spec ──▶ utils/spec-parser.js ProcessSpec (load, upgrade, dereference, group)
+        │                    └─ dispatches before-render on the host
+        ▼ resolvedSpec
+<rapi-doc> (src/rapidoc.ts) ──▶ templates/ ──▶ components/ (<api-request>, <api-response>, schema views)
+        ├── events: spec-loaded, nav-active-change   (components: before-try, after-try, request-aborted)
+        └── utils/mock-interceptor.js patches fetch / XMLHttpRequest while mock-server="true"
+
+@rapidoc/prerender ──▶ the same templates and components, serialized by its serializer.js
+                    renderTemplateToString (no DOM)
+```
+
+### Folder Contracts
+
+- [`src/`](./src/README.md): the three custom elements and the bundle entry.
+- [`src/components/`](./src/components/README.md): nested elements for request, response and
+  schema panels.
+- [`src/templates/`](./src/templates/README.md): Lit `html` functions bound to the host.
+- [`src/utils/`](./src/utils/README.md): spec pipeline, stable anchors, schema, request and mock
+  helpers; [`utils/mcp/`](./src/utils/mcp/README.md) for the MCP manifest, runtime and exported
+  project;
+  [`utils/arazzo/`](./src/utils/arazzo/README.md) for Arazzo workflow diagrams.
+- [`src/styles/`](./src/styles/README.md): stylesheets and the theme-token contract.
+- [`../rapidoc-prerender/src/`](../rapidoc-prerender/src/README.md): the `@rapidoc/prerender` renderer, a
+  separate package that renders this folder's templates.
+
+### Global Invariants
+
+- **No runtime dependencies for browser users**: everything is bundled into
+  `dist/rapidoc-min.js`.
+- **One spec shape**: `ProcessSpec` never rejects. It resolves to the parsed spec
+  (`info`, `tags`, `tagGroups`, `components`, `securitySchemes`, `servers`, ...) or to a result
+  with `specLoadError: true`, and templates, components and the static renderer all read it as
+  `this.resolvedSpec`.
+- **Stable anchors**: operation ids come from `utils/slugger.js` `OperationSlugger`; the static
+  sidebar and `@rapidoc/portal` depend on them and on `nav-active-change`, so changing the rules is
+  a breaking change (see `src/utils/README.md`).
+- **Boolean-like attributes are strings** (`allow-try="false"`) and are compared as strings.
+- **Semantic headings and parts**, **theme tokens** and **DSD hydration** follow
+  `packages/rapidoc/AGENTS.md` §5 and are checked by `tests/unit/semantic-markup.test.js` and
+  `tests/unit/css-variables.test.js`.
+- **Markdown** passes through `utils/sanitize.js` before `unsafeHTML`. In Node there is no
+  `DOMParser`, so the static renderer's markdown is not sanitized.
+
+### Global Side Effects
+
+- **Network**: spec and external `$ref` fetches, Try requests from `<api-request>`, OAuth token
+  requests and the sign-in popup.
+- **Global patching**: the mock server replaces `window.fetch` and three `XMLHttpRequest`
+  prototype methods and restores them on disable; importing `@rapidoc/prerender` installs or wraps
+  `customElements.define`; importing the elements configures the global `marked` instance.
+- **Storage and messaging**: `localStorage["rapidoc"]` with `persist-auth="true"`; OAuth replies
+  via `window.opener.postMessage` and a `BroadcastChannel`.
+- **URL and history**: `<rapi-doc>` replaces the location hash when `update-route="true"`;
+  `bindNavBar` pushes or replaces history for portal sidebars.
+
+### Verification
+
+From the monorepo root: `npm run test:unit`, then `npm run lint` and `npm run format-fix`. After
+any change under `src/`, run `npm run build:rapidoc`; never restore `dist/rapidoc-min.js` from git.
+
+---
+
 ## License
 
 MIT © [Mrinmoy Majumdar](https://github.com/mrin9)