Repository navigation
Release 2.3.0-beta.1 - #479
Merged
Merged
Conversation
Release 2.2.0
…#472) ## What changes for portal owners `fumadocs-openapi` 12.1.1 → 12.6.0, with `fumadocs-core` and `fumadocs-ui` 16.17.1 → 16.18.0 (12.6 requires 16.17.11 or later; the two must match). - **Playground OAuth sign-ins use PKCE** (12.5.0): the authorization request carries a `code_challenge`, the token request a `code_verifier`, so an authorization code that leaks on its way back is useless on its own. - **The token stays in the tab** (12.5.0): the playground keeps auth values in `sessionStorage` instead of `localStorage`; only the client ID is remembered across visits. - **The callback page sends no referrer**: `/oauth/callback` carries `<meta name="referrer" content="no-referrer">`, the policy Fumadocs' own `createOAuthHandler()` sets since 12.5.7. Without it the endpoint page's `document.referrer` held the callback address with the provider's code for the whole visit, and any analytics tag sent it as the page referrer. - **The playground opens from a "Try in Playground" button** and the example request and response are cards with selects (12.5.0); code blocks in operation descriptions are highlighted (12.5.5). ## What changed in the template - `oauth-callback.ts`, `oauth.callback.tsx`: 12.5.7 moved the page the playground returns to from a cookie to `sessionStorage['fumadocs-openapi-oauth']` (a fix for redirects other subdomains could control), so the callback takes it from there with `takeStartingPage()`, which reads the note and forgets it in one place. The outcomes, the same-origin check and the error page are unchanged; the "no authorization was started" page says "in this tab", since the note is per tab now. - `openapi-section.server.ts`: `DistributiveOmit` is no longer exported; spelled out locally. Fumadocs now writes one page for an operation that lists the same tag twice, so the refusal for that case is gone (the case-and-spacing one stays, and names a repeated tag once). - `.ai/instructions.md`: the documented `--ignore-minimum-release-age` flag does not exist in pnpm 11; `--config.minimumReleaseAge=0` is what works. Not needed for this PR any more: every version here is past the 7-day `minimumReleaseAge`, and the lockfile resolves without a flag. - `pnpm-workspace.yaml`: 12.5.6 moved fumadocs-openapi to chokidar 6 (engines `>= 22.22`) and undici 8 (`>= 22.19`), which fails the `--engine-strict` install on the CLI's Node 22.14 floor. The CLI never loads either: chokidar serves `generateFiles()` in watch mode and undici the server proxy, and the portal uses `staticSource()` and no proxy. So they are overridden to chokidar 5, which 12.5.0 shipped with, and to undici 7.30.1, the patched release that `@scalar/json-magic` 0.16 pins as well (its own `>undici` override is gone, since that older pin no longer exists). The alternative is raising the floor to Node 22.22, a breaking change; not taken here. **These overrides reach CI alone:** `npm install -g @apimatic/cli` ignores `pnpm-workspace.yaml`, prints an `EBADENGINE` warning for chokidar 6 and undici 8 on Node 22.14, and installs all the same; neither loads. - `package.json`: `lucide-react` 1.69.0 and `shiki` 4.6.0, the versions fumadocs 16.18 resolves to, and `pnpm dedupe`, so each has one copy (as does `@base-ui/react`), in the lockfile and in a fresh `npm install` tree alike. The petstore test build's home page loads 435 KB gzipped on a first visit (its HTML and every stylesheet and script it links), against 438 KB with the copies and 441 KB on dev. - `.github/workflows/portal_tests.yml`: a `tests_ref` input for `workflow_dispatch`, so a branch of `apimatic/v4-test-automation` can be run against a CLI branch before either lands. A push to dev still runs the suite's main. ## Tests - `oauth-callback.test.ts` runs the playground's own `requestOAuthToken` from `fumadocs-openapi/playground` in a stand-in tab, takes the note it wrote with `takeStartingPage()`, and hands it to `oauthCallback`: a move of the key upstream fails here, not in a portal. The refusal test adds a page path that does not read as an address. - `openapi-section.test.ts`: the duplicate-tag case now expects one page; `['pets', 'pets', 'Pets']` reads "lists the tags 'pets' and 'Pets'". - `navigation.test.ts`: a `null` `nav.json` no longer reaches the transformer, Fumadocs' loader reads a metadata file's data itself. - `request-examples.test.ts`: `OperationParameters.items` now requires `name`. - `portal-build.test.ts` (e2e): the callback page's referrer meta is asserted; the stylesheet budget is 128 KB (Fumadocs' new components took it from 93 KB to 119 KB, a `node_modules` scan would still blow past it); the description's code block is read as text, since it is highlighted now. Verified with `pnpm test` (type check, unit suite, lint) and `APIMATIC_E2E=1` on the e2e suite, and with a live sign-in: a portal built from a calculator spec with an `authorizationCode` scheme, driven in headless Chrome against a local fake provider. The authorize request carried `code_challenge_method=S256`, the token request `code_verifier` and the client secret in a Basic auth header, the callback sent the browser back through the session-storage note, the endpoint page's referrer was empty and a GA4 hit after the sign-in had `dr=null`. A `--frozen-lockfile --engine-strict` install passes on Node 22.14. **Portal automation tests:** the suite in `apimatic/v4-test-automation` drove the old inline playground; its update is apimatic/v4-test-automation#26 (WasifIsrar's 12.5 rework, #13, carried onto main with baselines from this build). Run on this branch with that suite: https://github.com/apimatic/apimatic-cli/actions/runs/43196475277. The two merge together; whichever lands first leaves dev's run red until the other does. Supersedes #441. ## Not in this PR - 12.6.1 (2026-11-11): `finishOAuthFlow()` rejecting with a provider's error, and `createOAuthHandler({ inline: true })`, a prerenderable redirect route. The template runs neither: its callback page shows the provider's error itself and never forwards it, and keeps its own page, which also explains a visit without a flow. It still reads Fumadocs' internal storage key, which the test above pins. Can come with a later bump once it is seven days old. - `openapiPlugin()` of `fumadocs-openapi/server` is deprecated in 12.6 in favour of `createOpenAPI().loaderPlugin()`. It still works; a follow-up. - The provider's answer is still forwarded in the endpoint page's address for the moment before the playground removes it (about 300 ms locally). That is Fumadocs' hand-off and the subject of fuma-nama/fumadocs#3809, closed without a change; the maintainer considers the sessionStorage verifier enough for the code flow, and the implicit flow's bearer token, which the same hand-off forwards, is raised there. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
…473) PR 1 of apimatic/apimatic-io#2348, with PR 3 (the other seven events) following in this same PR since 2026-11-12, so GA4 and GTM can be tested with every event before anything merges. PR 1: `portal.analytics` loads Google Tag Manager and GA4 from `apimatic.json`, and the template reports each page view once as `docs_page_view`. The detail and the code sketches are in apimatic/apimatic-io#2349. The build plan and the docs draft are kept out of the repository, so the squash brings neither into `dev`. Draft until the gate: `pnpm test` green, the manual list in apimatic/apimatic-io#2349 ("Manual, on a test portal") checked, and each of PR 3's events seen once in GTM Preview with all of its keys. The squash title then covers both: `feat(portal): load Google Tag Manager and GA4 from portal.analytics and report the portal events`. ## What is on the branch Read it from the entry point down. - **The root route** (`portal-template/src/routes/__root.tsx`) reports the first page's view on mount and one per `onRendered`; `head()` lists no script, and writes the `google-site-verification` meta when the identity file holds a value. - **The API page** (`portal-template/src/components/api-page.tsx`) renders the playground's header inside one element carrying the opt-out markers of the session replay tools a GTM tag may load (PostHog, FullStory, rrweb, Amplitude, Hotjar, Clarity, LogRocket) and the `data-portal-playground` test hook, with Fumadocs' endpoint bar while the playground's chunk loads. The cURL sample carries the same markers, since it follows what the reader types. The client is lazy-loaded from Fumadocs' public export, as Fumadocs itself loads it. - **The bundle's start** (`portal-template/src/lib/portal-analytics.ts`) runs at module evaluation, before React and before any vendor tag, never during prerendering: first `markPlaygroundDialogs()` (`lib/replay-markers.ts`), one observer that marks the playground's dialog as Fumadocs adds it, ahead of any replay tool's observer (until fuma-nama/fumadocs#3824 takes the markers itself), then `new Analytics(portal.analytics).start()`. - **The module** (`portal-template/src/lib/analytics.ts`) holds the event table and the `Analytics` class: `start()` creates `window.dataLayer`, pushes every vendor's setup entries and inserts the tags, once per page load, and under `portal serve` reloads the page when a config save changes the vendors; `report()` adds the cleaned `page_location` (`pageLocation()`), pushes `{ docs: null }` then `{ event, docs }`, and calls each adapter that sends for itself; `reportPageView()` and `reportNotFound()` keep the page history the two events need, and the not-found page reports only once the router has settled on it (`components/not-found.tsx`), so leaving it reports nothing for the page the reader goes to. Nothing is reported on `/oauth/callback`, and the tags wait while the address holds an OAuth answer (`holdsOAuthAnswer()` in `lib/oauth-callback.ts`): on the callback, and on the page a sign-in returns to until the playground has taken the answer out, which loads them (`analytics.loadTags()` from `components/playground.tsx`). - **The vendors** (`portal-template/src/lib/vendor-tags.ts`): the `adapters` registry is keyed by both vendors, so a vendor without an adapter does not compile. GTM pushes `gtm.start` and loads `gtm.js` (with the `environment` suffix when set), and reads the data layer itself. GA4 defines `window.gtag` only when missing, pushes `js` and `config` with `send_page_view: false`, loads `gtag/js`, sends each event under GA4's own name, and sets `page_location` on each page view, so GA4's own scroll and click events carry the cleaned address too. `insertTags()` appends each tag once, none while the address holds an OAuth answer. - **The reporters**: code copies report from each block's own copy button (`components/code-copy.tsx`, through Fumadocs' `Actions` slot) with the block's language ID, the IDs SDK downloads send too (`csharp`, `shellscript`), both through `languageId()`, which reads a name in lowercase and knows the common short names of languages outside the bundle (`kt` is `kotlin`), so one language is one value; MDX blocks get theirs at build time (`lib/transformer-language.ts`), the API reference's at render, and "Example Response", whose button Fumadocs keeps to itself, through a click handler on its card. The playground times its requests in a ref of its own and reports each result once (`components/playground.tsx`, `lib/api-request.ts`). The search dialog's report is `searchOutcome()` (`lib/search-report.ts`): the result picked goes out as a whole address in the form of `page_location`, and the term at most 100 characters long, which is what GA4 keeps. - **The shared type** (`portal-template/src/lib/portal-types.ts`, `PortalIdentity` in `src/types/portal/portal-config.ts`) carries `analytics` and `seo`, filled by `AnalyticsConfig` and `SeoConfig` from the `portal` block, with #2348's messages less its format rules: an ID, an environment value, the verification token and a kept name are any non-empty string, and no name is refused (decided 2026-11-12, to record in #2347); `portal generate` and `portal serve` warn when GA4 is set. - **The flag** (`--no-analytics` on `portal generate` and `portal serve`, defined once in `FlagsProvider`) reaches the actions as `PortalBuildOptions`, and `PortalSourceContext` applies it where the settings are read, for a build and for each config save under `portal serve`: both vendors are dropped, the kept query names stay. The options have no default, so every caller chooses. `portal serve` loads exactly what a hosted portal loads: no debug mode, no preview distinction, so the sketched `PortalDelivery` is not built (decided 2026-11-12, to record in #2347). - **The schema** (`apimatic.schema.json`) describes both blocks with no pattern, as the parser reads them; the schema test holds the two to one verdict per case. - **The end-to-end proof** (`test/e2e/portal-build.test.ts`, behind `APIMATIC_E2E=1`) builds the default fixture with both vendors and a verification value set: the IDs sit in a browser script, no prerendered page names the tag host, every page carries the meta, and the operation page holds the playground's prerendered header and the cURL sample each inside an element replays skip, and the copy button of "Example Response" as the `button[aria-live]` its copies are reported by, so a Fumadocs update that changes either fails here. `test/commands/portal/*-flags.test.ts` run both commands to see the flag reach the settings reader. Steps, as the plan numbers them: 1.1 the pure functions, 1.2 adapters and page views, 1.3 the loader's wait (built, then removed, see below), 1.4 the bundle wiring, 1.5 the verification meta and the playground out of replays, 1.6 the parser and the GA4 warning, 1.7 `--no-analytics`, 1.8 the schema, 1.9 the end-to-end proof, 1.10 README and docs. PR 1 is complete. In this PR, PR 3: 3.1 the three click reporters, 3.2 `docs_code_copy`, 3.3 `docs_search`, 3.4 `docs_not_found`, 3.5 `docs_api_request`, 3.6 the docs (done). PR 1 and PR 3 are complete; the gate below is what remains. PR 2 (`portal.scripts`) follows in its own PR. ## Before merging - [x] **No vendor tag reads an OAuth answer from the address** (`1bb6dfbb`): with 12.6.0 the playground reads a returned sign-in's answer from the address, so the tags wait until Fumadocs has taken it out, and an answer nothing takes out waits for the next page. Seen in headless Chrome against `portal serve` with both vendors: no tag at `#access_token=…&state=…`, both once the address was clean, and no GA4 hit carrying the token. - [ ] **Later, not a merge gate: take fumadocs-openapi 12.6.2 and have the callback hand the answer over as Fumadocs' `createOAuthHandler()` does**, so the answer never reaches the address at all. After a playground sign-in the provider lands on `/oauth/callback`, and our own callback copies its query and `#` part (`?code=…&state=…` or `#access_token=…`) onto the starting page, where the vendor tags read the address for themselves; the portal's own events are clean, since `pageLocation()` strips both. 12.6.2's `getReturnedFlow()` reads the answer from `sessionStorage` under `fumadocs-openapi-oauth-returned` and falls back to the address; 12.6.0 reads the address only, so the callback cannot store it there before the bump. With the bump: `oauthCallback()` returns the bare starting page and the route stores `location.href` under that key, with `test/portal-template/oauth-callback.test.ts` and the comment at `oauth-callback.ts:20` following. `dev` pins 12.6.0 since #472 merged on 2026-11-12, under the seven-day release-age rule in `pnpm-workspace.yaml`; 12.6.2 clears it on 2026-11-19, and this branch takes it then. The 5-second wait that held the tags back (step 1.3, commit `1c616d56`) was removed on 2026-11-12. - [ ] **Release together with PR 2 (`portal.scripts`).** PR 2 makes `--no-analytics` also leave out the `analytics` and `marketing` scripts, and updates the flag's help. Released alone, this PR would have the flag drop more in a later release than it does in this one. - [ ] **Follow-up, not a merge gate: a browser smoke test in apimatic/v4-test-automation**, from the Playwright scripts of the review of 2026-11-16: each of the eight events once with its keys, and leaving the not-found page. The components that report are not unit-tested, and they lean on Fumadocs' markup, storage keys and render order; what guards them here is the pinned event table, `searchOutcome()`, `apiRequest()` and the built-page checks. - [ ] **The manual list in apimatic/apimatic-io#2349** ("Manual, on a test portal with GTM Preview and GA4 DebugView"), with no debug mode: DebugView needs Tag Assistant or the Google Analytics Debugger extension on the test browser. - [ ] **Each of the eight events once in GTM Preview, with all of its keys**, as the docs draft's table lists them: a page view, a Markdown copy, an install copy (one `docs_plugin_install`, no `docs_code_copy`), an SDK download, a code copy from a page's block, the API reference's cURL sample and "Example Response", each with its language ID, a search with a pick and one without, a reopen without typing (nothing), a broken portal link (`docs_not_found` with the page left, plus its page view), and a playground request with a response and one that fails (`client_error`), with `docs_api_request` never carrying the request address. - [ ] **The "Done when" lines in apimatic/apimatic-io#2348** for loading, counting, nothing private, verification and events. ## Base Was stacked on #472 (fumadocs-openapi 12.6) while it was open, as the plan's section 3 says, so the diff showed only this work. #472 merged on 2026-11-12 as `f7fe7dff`, and this branch was rebased onto `dev` and retargeted the same day. An end-to-end run on 2026-11-13 (headless Chrome against `portal serve` and a built portal, with a real GA4 property) saw seven of the eight events arrive once each with their keys, and the playground dialog marked in the browser; the plugin event needs a project with a `plugin` block. It also found the first page view in `portal serve` carrying the site name as its title, fixed in `__root.tsx` by reporting directly only when the router is idle at mount. Decisions on record: the e2e list's "a `--no-analytics` build holds no ID" check is not in `test/e2e/portal-build.test.ts`; `test/infrastructure/portal-project-service.test.ts` checks the identity file written from a config without vendors instead, which saves a full build in CI (plan step 1.9). The code review of 2026-11-13 and the reviewer's findings of the same day are addressed from `be8cc928` on; the review of 2026-11-13 requesting changes from `09a22ba3` to `96885d4d`, with the OAuth return page in `1bb6dfbb`, but for a playground result that arrives after the reader closed the dialog, which Fumadocs gives no callback for in 12.6.0 or 12.6.2. The review of 2026-11-16 is addressed from `f54b30ef` to `02200bbc`, and settled four things customers will build on. The event names and keys are pinned by a test, as plain text apart from the interface, so a rename is a change made there on purpose. `status` stays one text value, the HTTP status as digits or `client_error`. A search's `result` is a whole address in the form of `page_location`. `ref` left the built-in kept names: no platform reads it from the address, sites use it for codes of their own, and a customer can add a name through `keepQueryParams` but cannot take one out. The same review found the not-found page reporting `docs_not_found` for the page a reader left it for; fixed, and seen in headless Chrome on a served and a built portal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
…nd next page cards (#476) Point 2 of apimatic/apimatic-io#2350: on an operation page, a long "Example Response" ran over the page's previous and next cards. ## What was wrong Since fumadocs-openapi 12.6 the example column of an operation page is sticky and no taller than the window, and the cards in it are meant to shrink to fit. Ours could not. The layout we render around them was a plain block, so each card kept its full height, and a long response ran out of the bottom of the column and over the previous and next cards. Because the column is sticky, the end of that response could not be scrolled to either. ## The fix - **The layout** (`example-layout.tsx`) takes the classes of Fumadocs' own default layout, `flex min-h-0 flex-col`, so the column's height reaches the cards. - **The request card** (`usage-tabs.tsx`) passes that height on at each box down to its code: the tabs, the open tab, the element marked for session replays, the block and its scroller. This is what Fumadocs' own request card does. With the layout change alone the overlap is gone, but our request card keeps its full height and the response card under a long sample is squeezed: to 131 px in a 1617 x 887 window, and to 44 px, its header only, at 1280 x 800. - **The example selector** loses `mb-2`. That margin used to collapse into the request card's own top margin; in a flex column it would add 8 px. The gap under the selector stays 16 px. Below the width where the column sits beside the page, nothing changes: the column is not capped there, and both cards keep their height. ## Pictures A neutral spec with a long request body and a long response, built with `portal generate`. Before, 1617 x 887, scrolled to the end of the page:  After, the same view:  After, 1280 x 800, at the top of the page:  ## Checked Measured in headless Chrome on a portal built from this branch: | Window | Before | After | | --- | --- | --- | | 1617 x 887 | cards of 636 and 642 px in a 799 px column: 511 px past it, over the footer cards | 382 and 385 px, inside the column | | 1280 x 800 | 598 px past a 712 px column | 338 and 342 px, inside the column | - Each card's code scrolls inside its card. - The TypeScript tab shrinks the same way, and the closed tab stays hidden. - A page with the example selector fits its column too, with the same 16 px under the selector as before. - At 1000 px and 390 px wide, where the column sits under the page, both cards are 636 and 642 px, as before. - `test/e2e/portal-build.test.ts`, the "portal build (end to end)" fixture: 45 passing. That includes a new check of the built page's boxes, the existing cURL marker check, and the template's type-check. I did not run the whole suite, and there is no browser test for this yet: the layout itself can only be held in `apimatic/v4-test-automation`. The other points of the issue are not in this PR. Points 3 to 6 are Fumadocs' own and are reported as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
…trings in their boxes (#478) Takes fumadocs-openapi from 12.6.0 to 12.6.5. That release fixes points 3 to 6 of apimatic/apimatic-io#2350, which we reported upstream as fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. With it, the playground's sign-in moves to the hand-over Fumadocs added in 12.6.2, which keeps the provider's answer out of page addresses. **12.6.5 is one day old, younger than the seven days `minimumReleaseAge` asks for.** It is merged early by decision: see "Merged before the seven days". ## What a portal gets - **A long field path in the playground stays in its panel** (points 4 and 5). The middle crumbs truncate, and Unset / Remove stay in reach. - **A long unbroken string wraps inside its box** (points 3 and 6): in a property card, a security scheme's card, and the field info popover. - **From 12.6.3, credentials are masked.** API keys and tokens are typed into password inputs, and the cURL sample shows a credential as `********`. - **From 12.6.3, the playground's rows look different.** An optional field outside the request is a muted row that one click adds; a field's name opens its description. - **From 12.6.4, the playground and the cURL sample build some requests correctly:** path parameter values are percent-encoded, form bodies keep `0`, `false` and empty fields, and cookie parameters are sent as the specification says. - **A sign-in's answer stays out of page addresses.** After a playground sign-in the reader lands back on the endpoint page at its own address; the provider's code or token no longer passes through it. The Google tags therefore load there at once, and a page opened through a link of its own ending in `?state=…` loads them too, where it used to wait for the next page. ## What changes here - `package.json`: `fumadocs-openapi` 12.6.5, and `lucide-react` 1.71.0, the lowest version 12.6.5 accepts, so there is still one copy of it. - `pnpm-lock.yaml`: five packages change (the two above, `@scalar/openapi-upgrader` 0.4.8, `@scalar/openapi-types` 0.9.9, and a new `@scalar/helpers` 0.17.1). - `pnpm-workspace.yaml`: `@scalar/json-magic` is held at 0.16.1 under `fumadocs-openapi`. 12.6.5 asks for 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's `--engine-strict` install would refuse it. This is the same hold `chokidar` and `undici` already have. - `usage-tabs.tsx`: one comment, which said the cURL sample shows typed credentials. The sign-in hand-over, in its own commit: - `oauth-callback.ts`, `oauth.callback.tsx`: the callback page leaves its address, the provider's answer in it, in the tab's session storage, where the playground reads it since 12.6.2, and sends the reader back to the page that started the flow at that page's own address. Until now it sent them back with the answer still in the query or the `#` part. - `vendor-tags.ts`, `analytics.ts`, `playground.tsx`: the tags no longer wait for an answer to leave the address. `insertTags()` holds back on the callback page alone, and `holdsOAuthAnswer()` and `Analytics.loadTags()` are gone. - `oauth-callback.test.ts`: a new test runs Fumadocs' own handler script beside ours and holds both to the same entry in the session and the same page, so a move of that entry upstream fails the test and not a portal. Apart from that, the template compiles and behaves as before against 12.6.5. ## Merged before the seven days `fumadocs-openapi@12.6.5` turns seven days old on 23 Nov 2026 at 11:58 UTC. #472 waited for that day. This PR does not: the decision is to take the fix now. What that costs until 23 Nov: - **A full re-resolution fails.** `pnpm dedupe` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` for `fumadocs-openapi@12.6.5`. A run that needs one adds `fumadocs-openapi@12.6.5` to `minimumReleaseAgeExclude` for that run only. - **Nothing else changes.** CI installs from the frozen lockfile, which never resolves, and `pnpm install` and `pnpm add` work as before. What speaks for the release: - It was published by Fumadocs' GitHub Actions with npm provenance, as 12.6.0 was, and it runs no install scripts. - The fix itself is one commit that changes class names in five files, fuma-nama/fumadocs@2419e7c. - The whole package was not compared with 12.6.0, and the step also takes in 12.6.1 to 12.6.4, which are three to five days old. - The other four new packages turn seven days old on 17 Nov, by 14:46 UTC. After 23 Nov, `pnpm dedupe --check` should pass without any exception. That is a check only: nothing in the lockfile needs to change. The lockfile here was resolved with a temporary `minimumReleaseAgeExclude` of five exact versions, which is not in this PR. ## A risk to know about Because of the `@scalar/json-magic` hold, the tests in this repository run json-magic 0.16.1, while an `npm install -g` of the CLI gets 0.19.1. The CLI loads this package (Fumadocs reads a specification through its magic proxy), and 0.19 rewrote that proxy. The portal tests workflow installs the packed CLI as npm does, so it covers the 0.19 side, but it runs on a push to `dev`, so only after this merges, and on Node 24. I checked that side by hand before then (below): on Node 24, and on Node 22.14.0, the CLI's floor, which is below the 22.19 that json-magic 0.19 declares. ## Checked - `test/e2e/portal-build.test.ts`: 78 passing, with the template's type-check against 12.6.5 among them. - `test/e2e/portal-serve.test.ts`: 6 passing. - The portal template's unit tests and the portal type tests: 550 passing. - No package in the lockfile is refused on Node 22.14.0 under `--engine-strict`. - I did not run the whole suite locally. In headless Chrome, on portals built from this branch with a neutral spec: | Problem | 12.6.0 | 12.6.5, as built | | --- | --- | --- | | Form under the request panel, three levels deep, 827 px wide | panel 425 px in a 400 px column | 400 px, middle crumbs truncate | | Unset hidden, five levels deep, 1142 px wide | panel 656 px in a 574 px column, Unset cannot be clicked | 574 px, Unset can be clicked | | Long inline code in a parameter's description | 7 px past the card's edge | inside the card | | Long string in the field info popover | 322 px of text in a 262 px box | no overflow | - **A playground sign-in, start to finish**, against a stand-in OAuth provider, through the hand-over: - The authorization code flow, with PKCE, and the implicit flow both sign in, and a request goes out with each one's token. - The reader returns from `/oauth/callback` to the endpoint page at its own address, the tags load there at once, and the entry the callback left in the session is gone once the playground has read it. - The refused case shows the provider's error on the callback page. - The callback page loads no tag and reports nothing, with an answer nobody started as well. A link from it loads the tags on the next page. - A page opened with `?state=CA` loads its tags at once and is reported without the parameter. - **The build a user gets**: the packed CLI installed with npm resolves 12.6.5 with json-magic 0.19.1, undici 8 and chokidar 6. It builds the same portal, and the four measurements above are the same. The tests above ran again after the hand-over commit. The four measurements, the npm-installed build and the Node 22.14.0 checks below ran before it; that commit changes the sign-in's browser code only. ### On Node 22.14.0 The packed CLI, installed by npm running on Node 22.14.0 (the official Windows build), as a customer on the CLI's lowest Node gets it: - **It installs**, with `EBADENGINE` warnings for `@scalar/json-magic@0.19.1`, `chokidar@6.0.0`, `undici@8.12.4` and `undici@8.12.3`. The first and the last are new with this PR: json-magic and the undici it pins. - **fumadocs-openapi 12.6.5 loads json-magic 0.19.1 there**, and its magic proxy follows a reference and a circular one. - **`portal generate` builds three portals:** the layout reproduction, the OAuth one, and a specification with nested, shared and circular `$ref`s across schemas, parameters, a request body and responses. - **The output is the same as this repository's install gives** (Node 24, json-magic 0.16.1). For two of those projects I compared every page's visible text and the data it is rendered from, the Markdown copies, the llms files and the search documents: 16 pages and 16 other files, none differ. - **`portal serve` works:** an operation page renders with its nested fields, the playground and the cURL sample, and saving the specification updates the page within two seconds. Not covered: Node 22.15 to 22.18 one by one, and macOS or Linux on 22.14 with json-magic 0.19. One thing this turned up that is not from this PR: an npm install resolves `zbsearch` 4.0.4 where the lockfile, on `dev` too, has 4.0.2, and the two write the search index differently inside. Its documents are the same. ## Pictures Five levels deep, 1142 px wide: the crumbs truncate and Unset is in reach.  A long inline code in a parameter's description, inside its card:  A long token in a security scheme's description, inside the popover:  ## Not in this PR - **Session replay markers on the playground dialog.** Fumadocs sets none yet, so the template still marks the dialog itself. ## After this merges - **#477 will conflict with it in two places.** That PR passes the listed scripts to `insertTags()` and edits `Analytics.loadTags()`, which this one removes. Whichever merges second resolves them: `insertTags()` keeps its new argument and the callback check, and `loadTags()` stays removed. - **apimatic/apimatic-io#2352 and the docs draft describe the old sign-in.** They say the tags wait on the page a sign-in returns to, and that a page opened with `?state=…` loads no tag. Both lines change with this PR. Part of apimatic/apimatic-io#2350 (points 3 to 6). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
sohail2721
requested review from
Shield-Jaguar and
saeedjamshaid
as code owners
November 17, 2026 09:47
|
mrafnadeem-apimatic
approved these changes
Nov 17, 2026
mrafnadeem-apimatic
self-requested a review
November 17, 2026 10:49
Contributor
|
🎉 This PR is included in version 2.3.0-beta.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



Promotes dev to beta, expected to publish 2.3.0-beta.1 to the npm
betadist-tag as a GitHub prerelease. The run commits nothing back to beta; the tag goes on this merge commit. dev already contains main's 2.2.0 merge, so the version continues from v2.2.0.Merge with Create a merge commit.
What releases
Everything on dev since v2.2.0. Two
featcommits and nothing marked!, so a minor version:#475 is a
cicommit and stays out of the notes.Before this beta goes to main
portal.scripts) is not in it. The analytics plan, apimatic/apimatic-io#2347, shipsportal.analyticsandportal.scriptsin one release, so the stable release waits for a beta that has both.🤖 Generated with Claude Code