Skip to content

Release 2.3.0-beta.1 - #479

Merged
sohail2721 merged 7 commits into
betafrom
dev
Nov 17, 2026
Merged

sohail2721 merged 7 commits into
betafrom
dev

Conversation

@sohail2721

Copy link
Copy Markdown
Contributor

Promotes dev to beta, expected to publish 2.3.0-beta.1 to the npm beta dist-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 feat commits and nothing marked !, so a minor version:

#475 is a ci commit and stays out of the notes.

Before this beta goes to main

  • feat(portal): load custom scripts from portal.scripts #477 (portal.scripts) is not in it. The analytics plan, apimatic/apimatic-io#2347, ships portal.analytics and portal.scripts in one release, so the stable release waits for a beta that has both.
  • Nothing automated covers the playground in this build. The portal tests fail on dev for the suite's own reasons: its playground tests still drive the inline form that 12.6 replaced with a dialog, and one petstore baseline is stale. QA's checklist for the analytics work is apimatic/apimatic-io#2352.

🤖 Generated with Claude Code

asadali214 and others added 7 commits November 5, 2026 10:22
…#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:

![The response card over the previous and next
cards](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-before.png)

After, the same view:

![Both cards inside the column, above the previous and next
cards](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-after.png)

After, 1280 x 800, at the top of the page:

![Both cards sharing the
column](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/example-column-after-1280.png)

## 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.

![The field path truncated, with Unset in
reach](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-path.png)

A long inline code in a parameter's description, inside its card:

![The inline code wrapped inside the property
card](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-card.png)

A long token in a security scheme's description, inside the popover:

![The long string wrapped inside the field info
popover](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-popover.png)

## 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>
@sonarqubecloud

Copy link
Copy Markdown

@sohail2721
sohail2721 merged commit ad99078 into beta Nov 17, 2026
16 of 19 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 2.3.0-beta.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants