Repository navigation
fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes - #478
Conversation
12.6.5 keeps a long field path in the playground inside its panel, with Unset and Remove in reach, and wraps long unbroken strings inside property cards and the field info popover: fuma-nama/fumadocs#3864 and #3865, points 3 to 6 of apimatic/apimatic-io#2350. lucide-react moves to 1.71.0, the lowest version 12.6.5 accepts, and pnpm dedupe leaves one copy of it, of shiki and of @base-ui/react. 12.6.5 asks for @scalar/json-magic 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's `--engine-strict` install would refuse it. It is held at 0.16.1, as chokidar and undici are held, and no package in the lockfile is refused on Node 22.14.0. Unlike those two the CLI loads it, and 0.19 rewrote its magic proxy: the tests here run 0.16's, an npm install runs 0.19's. Resolved with a temporary minimumReleaseAgeExclude of five exact versions, which is not committed. fumadocs-openapi 12.6.5 turns seven days old on 2026-11-23 at 11:58 UTC; lucide-react 1.71.0, @scalar/openapi-upgrader 0.4.8, @scalar/helpers 0.17.1 and @scalar/openapi-types 0.9.9 do on 2026-11-17. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…e as asterisks Since fumadocs-openapi 12.6.3 a code usage shows a typed credential as `********`. The sample still follows the playground's other edits, so it keeps the playground's replay markers. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…Node 22.14 An npm install on Node 22.14.0 warns for @scalar/json-magic 0.19.1 and for the undici 8.12.3 it pins, not for one package as the comment said. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…b's session Since fumadocs-openapi 12.6.2 the playground reads a returned sign-in from the tab's session storage, where Fumadocs' own handler leaves the callback's address. Our callback page now leaves it there too, 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 provider's answer still in the query or the `#` part. So no page but the callback has an answer in its address, and the tags no longer wait for one to be taken out: `insertTags()` holds back on the callback alone, `holdsOAuthAnswer()` and `Analytics.loadTags()` are gone, and the playground no longer calls for the tags. A page opened through a link of its own that ends in `?state=...` loads its tags at once. A test runs Fumadocs' handler script beside ours in a stand-in tab and holds both to the same entry in the session and the same page, so a move of that entry fails the test and not a portal. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
| # reads a specification through its magic proxy, which 0.19 rewrote. So the tests here run 0.16's proxy | ||
| # and an `npm install -g` runs 0.19's, with two more EBADENGINE warnings on Node 22.14, for it and for | ||
| # that undici; the portal tests install the packed CLI as npm does. | ||
| 'fumadocs-openapi>@scalar/json-magic': ^0.16.1 |
There was a problem hiding this comment.
CI tests @scalar/json-magic 0.16.1, while customers get 0.19.1.
Because of this override, every CI job runs json-magic 0.16.1. An npm install -g of the CLI ignores pnpm overrides and gets 0.19.1. That code runs in two places:
- in the CLI, where
create-page.jsanddereference.jscallcreateMagicProxy - in the portal's browser bundle, where
operation.jsandusage-tabs.jsimportgetRaw
I checked that 0.19 is safe on the path we use. fumadocs-openapi imports only createMagicProxy and getRaw from @scalar/json-magic/magic-proxy, and both exist in 0.16 and 0.19. In 0.19.1 the magic-proxy code doesn't load undici; only bundle/plugins/fetch-urls does. So the extra EBADENGINE warnings on Node 22.14 don't affect this path at runtime.
The gap is that nothing automated checks 0.19 before this merges. portal_tests.yml installs the packed CLI the way npm does, but it only runs on push to dev. It also has a workflow_dispatch trigger, so could you:
- Run
portal_tests.ymlon this branch (gh workflow run portal_tests.yml --ref chore/fumadocs-openapi-12-6-5) and link the run here before merging? Then the manual 0.19 checks in the description are backed by CI. - Open an issue to remove this pin, with its condition (the CLI's Node floor reaching 22.19), so it doesn't live only in this comment.
There was a problem hiding this comment.
First, an apology: you had already started a run on this branch (44030994779), and my dispatch cancelled it 32 minutes in, because the workflow cancels a run in progress on the same ref. I should have listed the runs first. I restarted one, and it has finished.
The run: https://github.com/apimatic/apimatic-cli/actions/runs/44035040377, on b105d56. The one commit after it changes a comment only.
What it backs. With the packed CLI installed as npm does, so with json-magic 0.19.1, these pass: generate the portal, visual, visual — nav.json, generate the auth portal and generate the petstore portal. So CI now covers 0.19 for building a portal and for the visual baselines.
It is not green, and neither is dev. Your baseline run on dev (44031027356, at 8e394e5) fails the same way. The same 16 tests fail in both runs, with the same messages:
artifacts: the petstorellms.txtbaseline lacks thelistPetVisitsline.functional: every auth playground test times out onlocator('#nd-page').locator('form').first(). That is the inline playground form, which the suite'smainstill drives; 12.6 moved the playground into a dialog. Each test waits out its two minutes, so the job runs into its 45-minute limit.
The branch run got two tests further than dev before that limit, the digest test and the petstore servers test, and both stop on the same missing form.
So neither failure comes from this PR, but the playground tests cannot vouch for 0.19, or for anything else in the playground, until the suite is updated. apimatic/v4-test-automation#26 is that update for 12.6; it is open and conflicts with main, and the new field rows of 12.6.3 will likely need the page object changed again.
The issue: apimatic/apimatic-io#2353, with the condition (the Node floor reaching 22.19, in engines.node and in the test matrix) and the steps to take the pin out.
I checked your reading of the code paths and agree. To be exact about the files: createMagicProxy is in utils/document/dereference.js, and getRaw in operation.js, ui/operation/usage-tabs.js, utils/create-page.js, utils/get-example-requests.js and utils/schema.js. In 0.19.1 nothing the magic proxy imports reaches undici; only bundle/plugins/fetch-urls/fetch-public-url.js loads it.
…s accepted The page a sign-in returns to loads its tags at once, while the provider's answer waits in the tab's session storage until a playground reads it. Tags read the address, not that storage, so the window is accepted, and the comment on `insertTags()` now says so, with the case of a page that mounts no playground. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
dev took fumadocs-openapi 12.6.5 (#478), where a sign-in's answer reaches the playground through the tab's session storage and no page's address but the OAuth callback's holds it. insertTags() there holds the Google tags back on the callback only, and Analytics.loadTags() is gone. Listed scripts follow the same rule here: none on the callback, and all on the next page view. They used to wait wherever the address held an answer, which no page a reader returns to does any more. The test that held them back at such an address now holds them back on the callback, and a second one loads them at once on a page whose own link carries a state parameter. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
🎉 This PR is included in version 2.3.0-beta.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
PR 2 of apimatic/apimatic-io#2348: `portal.scripts` and `window.apimatic.analytics.subscribe()`. PR 1 and PR 3 merged as #473. The plan this was built from, step by step, is apimatic/apimatic-io#2351; where the code departs from apimatic/apimatic-io#2347, #2348 and #2349 it says where and why. Since the review of 2026-11-17 it also carries `portal.analytics.googleConsentMode`, with which a consent tool can govern the built-in Google tags, and a `--no-analytics` that hands no event to the scripts it keeps. On 2026-11-18 it renamed three event keys that #473 had put out on the `beta` tag, and made a script's `category` required. The same day it answered a re-review of the fixes, whose ten new findings are under "Before merging". Ready for review. What is still to do before it merges is under "Before merging": the portal tests on this branch, the decisions to record in the issues, and releasing it together with #473. ## What a customer can now write ```json "portal": { "analytics": { "googleAnalytics": { "measurementId": "G-ABC123" }, "googleConsentMode": { "default": "denied" } }, "scripts": [ { "src": "static/js/consent.js", "category": "necessary" }, { "src": "https://cdn.example.com/chat.js", "category": "functional" }, { "src": "https://cdn.example.com/analytics.js" } ] } ``` - `src` is an `https` address or a file under `src/static/`. A file is checked on disk like a logo. - `category` is `necessary`, `functional`, `analytics` or `marketing`, the groups consent tools ask readers about. It is required: the CLI assumes none. The schema's description says what belongs in each. - The portal inserts each script after its own bundle and after the vendor tags, in list order, once per page, and never on the OAuth callback page. - `--no-analytics` on `portal generate` and `portal serve` leaves out the `analytics` and `marketing` scripts along with the two Google tags. The scripts it keeps are handed no event: `subscribe()` is there and stays silent. The consent default of `googleConsentMode` stays in such a build. - A script gets the portal's events from `window.apimatic.analytics.subscribe(callback)`: every event so far, then each new one, as a frozen `{ name, params, time, version: 1 }`. It returns the function that stops delivery. - `googleConsentMode` makes the portal queue Google's Consent Mode defaults ("denied", with a wait of 500 ms) before it sets either Google tag up. Both tags load as before and set no cookie until a consent tool calls `gtag('consent', 'update', …)`. Without the setting nothing changes. - Three event keys have new names. `docs_code_copy` carries `code_language` and `docs_sdk_download` carries `sdk_language`, where 2.3.0-beta.1 sends `language`. `docs_search` carries `picked_result`, where it sends `result`. ## What is on the branch One commit per step of the plan, then the fixes from two reviews, the merge with `dev`, the two follow-ups to the second review, five changes of 2026-11-18, seven commits that answer the re-review of that day, three that answer a review comment and SonarCloud after it, and four that answer the last of the review on 2026-11-19. | Commit | What it adds | |---|---| | `19cb032a` | `scripts` entries with an `https` address: parsed, written to `portal.identity.json`, inserted by the loader with `async = false`. The key a start runs once by covers the list, so a config save under `portal serve` reloads with the new one. An inserted tag is found by its `src` attribute, since a selector built from a customer's address misses on a backslash (replaced in `78505ad0`). | | `2580c4ea` | A file from `src/static/` as `src`: checked on disk with the brand's files, written as its portal path, inserted under the base path. | | `bf320b46` | `category`, and `--no-analytics` dropping the two categories. `PortalConfig.withoutVendors()` becomes `withoutAnalytics()`. The flag's help and the README say what it leaves out. | | `7849475b` | `EventFeed` and `window.apimatic.analytics`, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in `5f220732`. | | `cea1bc0c` | `scripts` in `apimatic.schema.json`, with one `httpsAddress` definition that `pluginUrl` now shares. | | `6782e26c` | The build test lists an address and a static file and checks the built files. | | `a0c6d999` | The fixture script that test ships holds a comment only. Its first version set a property on `window`, which the whole-tree lint that runs after the tests refused, and CI failed on it. | | `5f220732` | Scripts get a frozen `{ subscribe }` at `window.apimatic.analytics`, bound and put in place whatever was there; the feed is held at `window.portalEventFeed` (moved in `ddbad82a`). From the review of 2026-11-16 below. | | `88fe45dc`, `8d117512` | Two refactors from the same review: the feed's delivery is a static helper, and `insertTags()` reads `<head>` once per call (not at all since `78505ad0`). | | `6ed31b30` | `publish()` loops over the subscribers without copying them first, which SonarCloud flagged on this PR as needless. Two tests pin what the copy was guarding: a subscriber added, and one removed, while an event is being handed over. | | `310f38ab` | The merge with `dev`, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, and `dev` holds the Google tags back on the OAuth callback only. Listed scripts follow that rule: none on the callback, all on the next page. They used to wait wherever the address held an answer. | | `d9058be4` | A subscriber's callback is called on its own. It was called on the feed's record of that subscriber, so a callback written without strict mode got the record as `this`, and one that reset the record's count was handed the same event without end. From the review of 2026-11-17 below, as are the seven commits after it. | | `ddbad82a` | The feed and the mark of what the page started with are held by the window under one symbol. `window.portalEventFeed` is gone, and so is `window.portalAnalyticsStarted`, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page. | | `78505ad0` | The page remembers each address it inserted, so a script that removes its own element once it has run is not inserted again on the next page view. `insertTags()` no longer reads `<head>`. | | `97946a28` | A page that made `window.apimatic` read-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later. Since `f7518097` that error is left to a page that froze the object too. | | `bc7ec368` | `httpsAddress()` refuses an address with no host before its path (`https:///…`), as the schema's pattern does, and parses it once. `pluginUrl` goes through the same function. | | `e50ac0ac` | `Script.staticFiles()` answers a list, empty for an address, in place of `staticFile()` and its `null`. | | `5f1d49d9` | The flag's help and the README say that a script with no category is left out too. `367cf0be` takes that out again: no entry is without one. | | `07ee1f45` | `deliveredCount` and an `Unsubscribe` type replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line. | | `3df7c3dd` | The schema's description of `scripts` says they stay off the OAuth callback page. It still described the hold that the merge with `dev` removed. | | `17ddf35f` | A build made with `--no-analytics` hands no event to the scripts it keeps. `portal.identity.json` gains `analytics.eventFeed`, which is `"off"` for such a build (`analytics.events` since `6792fa8d`). `subscribe()` stays in place and silent, and the data layer gets its entries as before (it gets none since `b9450b72`). `AnalyticsConfig.withoutVendors()` becomes `withoutAnalytics()`, and the flag's help says what it does. Finding 7 of the review of 2026-11-17. | | `1547e424` | `portal.analytics.googleConsentMode`: the portal queues Google's consent defaults ahead of both vendors' setups, and a `--no-analytics` build queues none (it queues them since `a895b2cd`). Finding 2 of the same review. | | `440f0b28` | The setting in `apimatic.schema.json`, with the schema test holding it to the parser's verdict. | | `94c58970` | The build test sets it and checks that a built script holds the defaults and no prerendered page does. | | `be9556c2` | `language` on `docs_code_copy` and `docs_sdk_download` becomes `code_language` and `sdk_language`. gtag takes `language` on an event for the reader's own language, so GA4's language field read `python` for a code copy. A test keeps the name out of every event. From a review of the docs PR. | | `5ad3cfe8` | `result` on `docs_search` becomes `picked_result`. Next to `result_count` a reviewer read it as the list of results, sent empty. | | `367cf0be` | `category` is required on every entry, by the parser and the schema. No entry counts as `analytics` any more. The flag's help and the README lose "or not set". `oneOf()` loses its fallback, and `brand.colorMode` gets its default through `optional()`. | | `95780b18` | The state a window shares is `WindowAnalytics`, held under `WINDOW_ANALYTICS`, with a comment saying it means the `Window` object, which a reload replaces. "Page" in this code now means a route only. From a review comment on this PR, as is the next. | | `37db2b44` | `start()` keeps that state on the instance and is the one place that reads the global. An instance whose start asked for a reload used to find the state anyway, and its next page view inserted the new script into the window being left. It now adds no tag and hands over no event. | | `9a6e19b4` | `window.gtag` counts as a gtag only when it is a function. A browser answers that name with an element whose id is `gtag`, such as a guide's heading, and on a fresh load of such a page the portal called the heading and its whole script stopped. Portals with Google Analytics had this from #473. New finding 1 of the re-review, as are the six commits after it by their numbers. | | `7b491436` | The build test for the consent setting reads the setting's value, and a second build, without the setting, has to fail the same check. It used to look for two texts that every build holds. New finding 4. | | `a895b2cd` | A `--no-analytics` build keeps the consent default. A script such a build keeps may load a Google tag of its own. New finding 3. | | `eb200e91` | The schema's description of `googleConsentMode` says "Google's own tags", says that other vendors' tags in a container need their own consent checks, and no longer says "set here". New finding 5. | | `a3a04d3e` | The addresses the window remembers start with the `src` of every script `<head>` holds when the portal starts, so a script the host injects itself gets no second copy. New finding 7, a regression of `78505ad0`. | | `f7518097` | `analytics` is defined on the object a host keeps at `window.apimatic`, when that object takes a property. A copy is made only for one that does not. New finding 6. | | `ae99bcc1` | A backslash is refused anywhere before an https address's path, by the schema's pattern and the CLI's alike, and the report asks for "an address starting with 'https://' and a host". New finding 8. | | `37dcd1b3` | `gtagFor()` sets `window.gtag` before it returns it, not inside the return expression, which SonarCloud flagged (S1121) after `9a6e19b4`. | | `b9450b72` | A `--no-analytics` build writes no event to `window.dataLayer` either: `report()` returns at once. The consent default, queued in `start()`, is the one thing such a build puts there. From a review comment on this PR. | | `6792fa8d` | The identity's switch is `analytics.events`, no longer `analytics.eventFeed`, since it turns off the data layer's events too. It is still refused as a setting in `apimatic.json`. | | `15aaf820` | The schema's description of `scripts` names the token an OAuth 2.0 sign-in leaves in session storage among what a listed script can read. Tracked in apimatic/apimatic-io#2355; wording from the review. | | `144c6b73` | The schema's description of `googleConsentMode` says it does not affect which scripts in `portal.scripts` are loaded, or when, in place of "holds back no script". Wording from the review. | | `482418b2` | The schema's description of a script's `category` says what belongs in each of the four, with examples, and that a script doing more than one thing takes the last that applies. From the review. | | `665c8ef9` | `windowGtag()`, `scriptsInHead()` and `putOn()` are inlined where they were called, by the rule `3fc4fdd3` adds to `.ai/instructions.md`: each one's doc comment, signature and brace outweighed its body. Nothing changes in what the portal does. | ## Decisions on record Each is a departure from the issues, made with the reviewer during the build and written up in apimatic/apimatic-io#2351 (section 4 and section 1, row 22), except the four that answer the review of 2026-11-17 and the last two, of 2026-11-18, which are written up here only. The issues themselves are not edited yet. - **No `attributes`.** An entry is `{ src, category }`. A file in `static/` can add a vendor's tag and set its attributes, and Plausible, the issues' example, now gives out a site-specific address with an inline call. Adding the key later breaks no config. - **`category` is not written to the identity file.** Nothing in the browser reads it in this release. - **Two reports for `src`, not three.** What is neither an `https` address nor a file in `static/` gets one report naming both choices. - **Events from before a subscription arrive just after `subscribe()` returns**, not inside it, so `const stop = subscribe(…)` can call `stop()` on the first event. - **`toJSON()` does not write `scripts`**, as it writes neither `analytics` nor `seo`. - **No second Vite build for `--no-analytics` in the build test.** `portal-project-service.test.ts` proves the identity file, as for #473. - **The flag's help** is `leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay.` "The Google Tag Manager and Google Analytics tags" became "the tags", and `17ddf35f` added the events. `5f1d49d9` had added "or not set", which `367cf0be` took out with the default. - **A `--no-analytics` build hands no event to the scripts it keeps** (`17ddf35f`). This reverses a bullet written here earlier on 2026-11-17, which called the open feed a design choice. `subscribe()` stays in place, so a kept script does not throw on a staging build. - **A `--no-analytics` build writes no event to the data layer either** (`b9450b72`). This reverses what stood in the bullet above until 2026-11-18: "the data layer still gets its entries: no vendor reads them there". Since `a895b2cd` keeps the consent default for a Google tag a kept script loads, a vendor can read them there: a tag manager such a script loads fires on the data layer's events. The cost is that a preview made with the flag no longer shows in the console what would have been reported. - **Consent Mode defaults are queued in the setup, and nothing is held back.** #2347 already says GTM and GA4 are never held back and get Consent Mode defaults in their setup. Holding the tags until `necessary` scripts have run was considered and not built: it needs a queue for events, delays analytics by the slowest script, never starts if one hangs, and still races for a consent tool that sets its default late. - **`googleConsentMode` is Google's alone.** It is `{ "default": "denied" }`, an object so that a later key changes no config, and it holds no listed script. The portal-wide consent setting of #2347, which holds scripts by category and gives `window.apimatic.consent.update`, stays a later phase under a key of its own. - **The wait is fixed at 500 ms, and "denied" covers the four Consent Mode v2 types.** The setting is accepted with no built-in tag, for a Google snippet the customer lists themselves. - **A `--no-analytics` build keeps the consent default** (`a895b2cd`). This reverses what stood here until 2026-11-18, that such a build queues nothing for Google. It keeps `necessary` and `functional` scripts, and an owner may load Google's own snippet from one of those, the route this description gives for no contact with Google before consent. On staging only, that snippet then started with no consent state. The default does nothing where no Google tag loads. - **`category` is required** (`367cf0be`). This reverses the default of `analytics` that #2351 records. A reviewer's point: a customer who never chose a category has no way to see why `--no-analytics` dropped a script. What the default guarded still holds, since only a script someone marked `necessary` or `functional` survives the flag. A missing category is reported as `'portal.scripts[0].category' is required.` No release has `scripts`, so no config breaks. - **The four categories stay, and each is defined** (`482418b2`). The review asked why there are four when two behave alike today, `necessary` with `functional` and `analytics` with `marketing`. They are the groups consent tools ask readers about: Cookiebot's necessary, preferences, statistics and marketing, and OneTrust's strictly necessary, functional, performance and targeting. #2347 records them for that reason, for the later consent setting that holds each script until the reader agrees to its group. That setting needs both splits: a reader may accept statistics and refuse marketing, and a chat widget can wait for consent where a consent tool cannot. Merging two names now would leave every config that used the merged one meaning the wrong thing once they split. `preferences` is what `functional` covers, and a fifth group, such as OneTrust's social media, can be added later without breaking a config. - **Three value-object methods keep their own place** although they fall under the rule of `3fc4fdd3`: `AnalyticsConfig.withoutAnalytics()`, `Script.staticFiles()` and `Script.loadsWithoutAnalytics()`. Each answers from private state, so inlining it would mean exposing that state to its caller. - **Three event keys are renamed after #473 went out on the `beta` tag** (`be9556c2`, `5ad3cfe8`). A container built against 2.3.0-beta.1 that reads `docs.language` or `docs.result` gets nothing from them after this, with no error. The docs were not published with that beta. ## Known limits - **A listed script that never answers.** Measured in headless Chrome with a host that accepts the connection and sends nothing: the page, GTM, GA4 and page views are unaffected, but the listed scripts after it do not run while it is pending. On a built portal the window's `load` event also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Under `portal serve` `load` had already fired. A script that fails outright (a host that does not resolve) holds nothing. - **No consent gating.** Every listed script loads for every reader, whatever its category, unless the build used `--no-analytics`. - **Without `googleConsentMode`, a listed consent script can still lose to the built-in Google tags.** Measured with Google Analytics and the consent script 1.5 s late: Google set its `_ga` cookies and sent the page view with no consent state. With the setting on, the same run set no cookie and marked the page view denied. A customer whose banner decides what is tracked has to set it, and the docs must say so. - **A consent tool's own default replaces the portal's, wait included.** A stand-in that queued its own "denied" default, with no wait, after the portal's kept the state denied, and a returning reader's first page view then went out as denied. With no second default the wait held and it went out as granted. - **`googleConsentMode` is Google's advanced Consent Mode.** Both tags load before the reader answers and send hits marked denied, with no cookie. A customer who wants no contact with Google before consent lists Google's own snippet from a file of theirs that waits; list order holds (measured). - **No `integrity`.** The key is refused as unknown, so a build fixes a script's address but not what it serves. A script listed by its address runs whatever the address serves at each page load: a change by its vendor, or by anyone who takes the address over, reaches a published portal without a rebuild. A file in `static/` changes only with a rebuild, apart from code it loads from elsewhere. Documented rather than fixed, for now: a [review comment on apimatic/apimatic-docs#887](apimatic/apimatic-docs#887 (comment)) asks the scripts warning to say so. An optional `integrity` key can come later without breaking a config. - **Any listed script can read the page**, the API playground included. The replay markers, and keeping scripts off the OAuth callback, limit what a well-behaved vendor script picks up; they do not sandbox a script. - **On the page a sign-in returns to, listed scripts load at once, while the provider's answer still waits in the tab's session storage.** Since the merge with `dev` (#478) the answer is in no page's address but the callback's, where nothing loads. It waits in session storage until a playground reads it, and on a page with no playground it stays for the life of the tab. A listed script that reads session storage can read it there: seen in a browser, a script starting on the returned page read the callback's address, `code` included. #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is tracked in apimatic/apimatic-io#2355: the schema's description of `scripts` names the token (`15aaf820`), and fuma-nama/fumadocs#3874 asks Fumadocs for an option to keep it out of session storage. Whether portals must keep it out of listed scripts' reach altogether is still to decide. Holding them until the playground has taken the answer would not keep a credential from them. Measured with a sign-in through the playground against a stub provider that answers in the implicit flow: a listed script starting on the returned page read the token in the waiting answer; the playground then kept the token in session storage, as `fumadocs-openapi-auth-oauth`, for the life of the tab; and the same script read it there at its next start, on a guide page with no playground. - **`window.apimatic` does not exist for a script the host injects into `<head>` itself**, which runs before the portal's bundle. If such a script puts an object of its own at `window.apimatic.analytics`, the portal replaces it at its start, and callbacks queued on the old one are not carried over. - **A page that made `window.apimatic` read-only and froze its object gets no `subscribe()`.** The portal starts and works, and the error shows in the console. A listed script that calls `window.apimatic.analytics.subscribe()` fails there. Where the object behind the read-only name still takes a property, the portal puts `analytics` on it and nothing is in error (`f7518097`; seen in a browser for a read-only property, not run again for a getter alone). - **A script the host injects is told from a listed one by its `src` as written.** The same file under another spelling of its address, relative where the portal writes it from the root, gets a second copy. - **The schema passes three malformed hosts that the CLI refuses:** `https://:443/…`, `https://[::1/…` and `https://cdn.exa%mple.com/…`. An editor shows no warning for them, and `portal generate` reports the address. ## Risk **Medium.** #473 is out on the `beta` tag only, as 2.3.0-beta.1 (`latest` is 2.2.0, which has none of it). Nothing of this PR is released, and it builds on #473. - **What changes for every portal, scripts listed or not:** - The loader remembers the addresses it has inserted, and reads `<head>` once, at its start, for the scripts already there. This applies to the two Google tags too. It takes `window.gtag` as Google's only when it is a function: a browser answers that name with an element whose id is `gtag`, such as a guide's heading, and `dev`'s GA4 tag calls whatever the name holds, which stops the portal's script on such a page. - The mark of a started page, which #473 kept at `window.portalAnalyticsStarted`, is held under a symbol on the window with the feed. - Every portal gets `window.apimatic.analytics`, and keeps each reported event in memory for the life of the page. - `portal.identity.json` gains `analytics.googleConsentMode` and `analytics.events`. A portal that sets no consent mode queues nothing new, and its events are on. - `pluginUrl` is checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. A `pluginUrl` with no host before its path (`https:///…`) or with a backslash in its host (`https://host\x.zip`) is now refused; the CLI used to accept both, writing the first without the extra slash and the second with a slash for the backslash. A portal with no `scripts` loads nothing new. - **What changes only for a portal that lists scripts:** those scripts run on every page, the API playground included, with full access to the page. That is the feature, and choosing them is the customer's. - **What cannot be taken back after a release:** the shape of an entry, the four category names and that one is required, `window.apimatic.analytics.subscribe()`, the event it hands over and the keys of each event, and `googleConsentMode` with its one value. Customers will write configs and scripts against them. - **What stands between this and a mistake:** - CI: the whole suite and the lint, on three systems and four Node versions. - Both end-to-end files. - The browser checks under "Test plan, in a browser". - A code review at `6782e26c`, whose five findings are fixed. - A second code review, by a colleague, at `6ed31b30`, and a re-review at `94c58970`. Their fourteen and ten findings are answered under "Before merging". - Two security reviews, the second on `6ed31b30`, which found no vulnerability. - **Where the cover is thin:** - The browser checks were Chrome, with one run each in Firefox and in WebKit on Windows. Safari itself was not run. - The sign-in path was checked by opening the callback by hand, with a typed `code` and `state` and the starting page put in session storage, not with a provider's round trip. One sign-in was then run through the playground itself, against a stub provider that answered in the implicit flow. No real provider has been used. - Real vendors' scripts run: Google's GA4 snippet with a `subscribe()` forwarder (at `6ed31b30`), an open-source consent tool and an open-source session recorder. Not run: a commercial consent tool or replay tool, a chat widget, Segment, or a vendor that reads `data-` attributes. - The thirteen commits after the merge (the second review's fixes and its two follow-ups) have tests and both end-to-end files behind them, and a browser run each: on a preview for the first eight, and on built files too for the consent mode and `--no-analytics`. The re-review at `94c58970` read them; none has had a security review. - The five commits of 2026-11-18 have tests behind them. The first three also have the build end-to-end file, a browser run for the two renames and a run of `portal generate` for the required category. The last two have a browser run on a preview. None has had a code or security review beyond the comment the last two answer, and neither end-to-end file was run locally for the last two. - The seven commits that answer the re-review have tests, both end-to-end files and a browser run on built files behind them, or a run of `portal generate` for the address rule. None has had a code or security review. Two of them change what a host sees: where `analytics` is put on `window.apimatic`, and which scripts in `<head>` count as inserted. - The three commits after them have tests, both end-to-end files and a browser run on a `--no-analytics` build behind them. None has had a code or security review beyond the comment and the SonarCloud issue they answer. - The four commits of 2026-11-19 change three schema descriptions and inline three helpers. They have the schema test, the unit files, both end-to-end files and a browser run on built files behind them, and no other review. - The one real consent tool run against `googleConsentMode` is open source and wired to Consent Mode by hand, as its guide shows. A commercial tool that queues its own default may behave as the stand-in did (see "Known limits"). - The merge with `dev` (`310f38ab`) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files, a browser run and the re-review at `94c58970` behind it, but no security review. - **No data or state to migrate.** Nothing is stored, and `portal.identity.json` is rewritten on every run. ## How to revert - **On `dev`, before a release:** revert this PR's squash commit with `git revert`. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes `--no-analytics` back to leaving out the two Google tags only, with its earlier help text and README lines, and takes `scripts` and `googleConsentMode` out of the schema. - **After a release:** prefer a fix forward. A revert breaks every config that lists scripts or sets `googleConsentMode`: a CLI without this change refuses both as unknown settings, so `portal generate` and `portal serve` fail until the customer removes them. - **A portal already published keeps what it was built with.** It is static files, so reverting the CLI takes no script off a live portal. To stop one, remove its entry from `apimatic.json`, rebuild and redeploy. For `analytics` and `marketing` scripts, building with `--no-analytics` does the same. - **For one customer, without touching the CLI:** remove `scripts` from `apimatic.json` and rebuild. The portal then loads none, and `window.apimatic.analytics` stays there unused. - **There is no feature flag.** ## Before merging - [ ] **Release together with #473.** This PR is what that PR's "Release together with PR 2" item waits for: until it merges, `dev` holds a `--no-analytics` that drops less than it will. - [x] **CI green on `6ed31b30`**, the last commit before the merge with `dev`: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On `6782e26c` the tests passed (2,526 on `ubuntu-latest / Node 24`) and the lint after them failed on the fixture script, which `a0c6d999` fixes. The whole suite was not run locally. - [x] **CI green on `310f38ab`**, the merge with `dev`: all 16 checks. - [x] **CI green on `07ee1f45`**, after the second review's fixes: all 16 checks. - [x] **CI green on `94c58970`**: all 16 checks. - [x] **CI green on `367cf0be`**: all 16 checks. - [x] **CI green on `37db2b44`**: all 16 checks. - [x] **CI green on `ae99bcc1`**: all 16 checks. - [x] **CI green on `6792fa8d`**: all 16 checks. - [x] **CI green on `665c8ef9`**, the head: all 16 checks. - [x] **The re-review at `94c58970`** (a second review, which read the fixes at that commit and raised ten new findings). Each was checked first: the dead page of finding 1 was reproduced on built files, and finding 4 on two builds. Fixed: a heading called "gtag" stopped the portal's script (1, `9a6e19b4`); a staging build dropped the consent default (3, `a895b2cd`); the consent setting's build test could not fail (4, `7b491436`); the schema promised more than Consent Mode does (5, `eb200e91`); a host's own object at `window.apimatic` was swapped for a copy (6, `f7518097`); a script the host injects was loaded twice (7, `a3a04d3e`); a backslash passed for a host (8, `ae99bcc1`); a config save could insert the new script into the window being left (9, `37db2b44`, which a comment on this PR asked for). Not changed: listed scripts can read a sign-in's answer in session storage (2), tracked in apimatic/apimatic-io#2355, since holding them would not keep the token from them (see "Known limits"); and the list of wanted scripts is still built on each page view, and two field comments stay (10). - [x] **The review of 2026-11-16** (a code review of this PR, findings checked by hand). Fixed in `5f220732` and the two refactors after it: `window.apimatic.analytics` was the feed object itself, so `publish()` and the event list were reachable from any script; `subscribe` threw when called detached from that object; an object a page had already put at that name made every report throw; `EventFeed.deliver()` was a private instance method, which `.ai/instructions.md` rules out; and `insertTags()` read `<head>` once per script. Seen in a browser with a page's own stand-in set first. Left as they are, on purpose: an address with a space around it is refused while a static path with one is accepted; the event history is not capped; missing-file checks read a folder once per file. A security review of the diff found no vulnerability. - [x] **The review of 2026-11-17** (a colleague's review at `6ed31b30`, fourteen findings, each checked against the head, the runtime ones reproduced in a browser or in Node first). Fixed in the eight commits after the merge: a script that removes its own element was inserted again on every page view (1, and 10 with it); the feed was reachable at `window.portalEventFeed` (3); a page that had made `window.apimatic` read-only stopped the bundle (4); a callback got the feed's record of it as `this` (5); the CLI accepted and rewrote `https:///…`, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9); `staticFile()` answered `null` (12); three comments restated the code (14). Fixed after those, on the reviewer's word: a listed consent script could not hold back the built-in Google tags (2), by `googleConsentMode` in `1547e424`; and `--no-analytics` handed events to the scripts it kept (7), in `17ddf35f`. Left as they are, on purpose: the event history is not capped (8), as after the first review; the browser tells a portal file from an address by its leading `/` (13), which is the rule `api-markdown.tsx` on `dev` uses for images, and tests pin what the CLI writes; `isWebAddress()`, which checks links and the site address, keeps its own rule (the rest of 11). - [x] **The manual list** is closed. Three of its checks were run with real tools on 2026-11-17 and are in the browser list; the others were dropped: each is covered by a run above or by a test, is a docs example, or is optional. - [x] **Review comments.** Rafay's two, both on `analytics.ts`: the name of the state a window shares (answered by `95780b18` and `37db2b44`, resolved), and `--no-analytics` writing every event to the data layer (answered by `b9450b72`, resolved). SonarCloud's one new issue on this PR, S1121 in `vendor-tags.ts`, is answered by `37dcd1b3`. Rafay's last three, on `apimatic.schema.json`: the sign-in token in the description of `scripts` (`15aaf820`, resolved), plain words for what `googleConsentMode` leaves to listed scripts (`144c6b73`, resolved), and defining the four categories and saying why there are four (`482418b2` and "Decisions on record", answered and left open for Rafay). The rule Rafay added to `.ai/instructions.md` in `3fc4fdd3` is applied by `665c8ef9`. - [x] **The docs**, in apimatic/apimatic-docs#887 at `0b13cb5c`, have the `portal.scripts` page with `category` required, the CLI row with the flag's wording, a consent section for `googleConsentMode`, the sign-in section as it works since #478, the three renamed event keys, and what the re-review's fixes change for a reader of them, and what belongs in each category. That PR stays a draft until this is in a full release. - [ ] **apimatic/apimatic-io#2347, #2348 and #2349** record the decisions above. - [ ] **The portal tests** of apimatic/v4-test-automation, which run on a push to `dev` and not on a pull request: dispatch them on this branch. ## Test plan, automated Run on the tree of `6782e26c`; the lint and the analytics and feed tests again on `6ed31b30`, and the build test on `8d117512`. After the merge with `dev`, on `310f38ab`: `tsc` for all three, `eslint .`, every `test/portal-template` file with the config, schema and flag tests (1,130 passing), and both end-to-end files (79 and 6 passing). After the second review's fixes, on the tree of `07ee1f45`: `tsc` for all three, every `test/portal-template` and `test/types/portal` file with the schema, flag, `portal-source-context`, `portal-project-service`, `serve` and `quickstart` tests (1,449 passing), and both end-to-end files (79 and 6 passing); `eslint .` on `07ee1f45` itself. After the two follow-ups, on the tree of `94c58970`: `tsc` for all three, those unit files with `prepare-project` and `portal-template.test.ts` (1,491 passing), and both end-to-end files (80 and 6 passing); `eslint .` on `94c58970` itself. `17ddf35f` and `1547e424` each passed the type checks and those unit files on their own. After the three commits of 2026-11-18, on the tree of `367cf0be`: `tsc` for the CLI and the tests, the unit files those commits touch with the config, schema, source, project, serve and template ones (792 passing), `test/e2e/portal-build.test.ts` (80 passing) and `eslint .`. `tsc` for the template was run after the two renames, which are all that touch it. After `37db2b44`: `tsc` for the template and the tests, the analytics and feed tests (100 passing) and `eslint .`. After the seven commits that answer the re-review, on `ae99bcc1`: `tsc` for all three, the config, schema, source, project, serve and template unit files (804 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the three commits that follow, on `6792fa8d`: `tsc` for all three, the same unit files (805 passing), both end-to-end files (81 and 6 passing) and `eslint .`. After the four of 2026-11-19, on `665c8ef9`: the same again (805, 81 and 6 passing), with the schema test after each schema commit. - [x] `tsc` for the CLI, the tests and the template (the template's known errors from ungenerated files only). - [x] `eslint` on each step's CLI and test files, and `prettier` on every changed TypeScript file. Neither reads the schema, and `eslint` skips the template's `lib/`. - [x] Unit: `portal-config`, `portal-source-context`, `preview-config`, `portal-project-service`, `schema`, `analytics`, `event-feed`, `portal-template`, and the action and command tests that read the default fixture. Each step added tests to its own files. - [x] `eslint .`, the whole tree, as CI runs it after the tests: clean on `6ed31b30`, on `07ee1f45`, on `94c58970`, on the tree of `367cf0be`, on `ae99bcc1`, on `6792fa8d` and on `665c8ef9`. - [x] `APIMATIC_E2E=1` with `test/e2e/portal-build.test.ts`: 81 passing on `ae99bcc1`, 80 on `94c58970` and on the tree of `367cf0be`, 79 before the consent mode's test. `APIMATIC_E2E=1` with `test/e2e/portal-serve.test.ts`: 6 passing, again on `ae99bcc1`. Both again on `6792fa8d` and `665c8ef9`: 81 and 6. ## Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit) Against `portal serve` and against `portal generate` output served statically, with GTM and GA4 set. Listed addresses pointed at a local `https` host, so order, delay, failure and silence were exact. - [x] **Order and place.** Scripts sit in `<head>` after the vendor tags, `async` false, and run in list order with the first served 1.5 s late. Seen on a preview and on a built portal. No prerendered page names one. - [x] **Once per page.** After three page changes through the portal's links, each element is there once, ran once and was fetched once, an address with a `\` in its query included. - [x] **A static file.** Loads from `/js/…`, and from `/docs/js/…` with a path in `portal.site.url`, on a preview and on a built portal. - [x] **A missing file.** `portal generate` fails naming `portal.scripts[1].src`, and names the spelling on disk when only the case differs. A config save under `serve` that names one is refused and the page keeps what it had. - [x] **Categories** (run before `367cf0be`, when an entry could still have none). Six probes (one per category, one with none, one static file marked `necessary`). Without the flag all six run, on a preview and a built portal. With `--no-analytics`, on both: only the `necessary` and `functional` ones run, the host is never asked for the others, no Google tag is on the page, the page view is still reported. In the built files, none of 138 holds a dropped address or either ID. - [x] **Config saves under `serve`.** Adding a script reloads the page with it. Editing the description reloads nothing. Under `--no-analytics`, adding an `analytics` script changes nothing and adding a `necessary` one reloads with it. - [x] **Subscribe.** A listed file with four subscribers: a forwarder got the page view from before it loaded, then two page changes, a code copy and a search, the same five events in the same order as the data layer. Each had exactly `name`, `params`, `time`, `version`, both objects frozen. A subscriber that tried to change events changed nothing the next one saw. A one-time subscriber got one event and stopped. A throwing one showed one console error per event and stopped nothing. All of this on a preview; on a built portal under a path, the replay, a page change, the one-time subscriber and the throwing one. - [x] **Through a config save.** A subscriber from before a save that changed nothing got the next page view. - [x] **Around a sign-in** (preview, on `310f38ab`). On `/oauth/callback?code=…&state=…`: no vendor tag, no listed script, no page view. Sent back from the callback to the page that started the sign-in: that page's address is its own, the tag and every listed script load at once, and the page view has the clean address. A listed script starting there could read the answer in session storage; on the API reference page it was gone once the playground had loaded, and on a guide page it stayed. The callback was opened by hand with a typed `code` and `state`, and the starting page put in session storage, not a provider's round trip. - [x] **A `state` of the customer's own** (`?state=CA`, and `?code=…&state=…` in a page's own link; on `310f38ab`): the tag and every listed script load at once, and the page view is reported without them. - [x] **A script that fails** (a host that does not resolve), first in the list: the next ones run, the page works. - [x] **A script that never answers**, first and last in the list: see "Known limits". - [x] **Replay markers.** A listed script with its own `MutationObserver` saw the playground dialog already carrying every marker. - [x] **A script that removes its own element** (preview, on the tree of `07ee1f45`). Before the fix it ran twice on the first page and once more on each page change. After it, once for the whole visit, across three page changes. - [x] **A page that locked `window.apimatic`** (same preview), read-only and with a getter alone. Before the fix the bundle threw and the page never came to life: no theme switch, no listed script, no Google tag. After it the theme switch works, the Google tag and the listed scripts load, and the console shows the error. Run on the tree of `07ee1f45`; since `f7518097` the read-only case gets `subscribe()` and shows no error (below). - [x] **What the window holds** (same preview). No name on the window holds `portal`, and `window.apimatic.analytics` has `subscribe` alone, frozen. A callback written without strict mode that pushes to `this.vendorQueue` filled `window.vendorQueue`. - [x] **Config saves again** (same preview). Saving a description reloads nothing, runs no script again and keeps the subscriber. Adding a script reloads the page with it. - [x] **A consent script against the built-in tags** (on the tree of `94c58970`; every hit was answered in the browser, so none reached Google). With `googleConsentMode` and a consent stand-in 1.5 s late: the data layer leads with the portal's default, no cookie is set, and the page view is marked denied, on a preview and on built files. Without the setting the same run set `_ga` cookies and sent the page view with no consent state. - [x] **A reader who agrees** (preview). After `gtag('consent', 'update', …)` the cookies appear and the next hit is marked granted. A returning reader whose answer came 300 ms after Google's library ran got a first page view marked granted. - [x] **A GTM container** (preview, GTM-KRV5DMCJ) with the setting: the default leads the data layer, no cookie is set, and hits are marked denied. - [x] **A config save that adds the setting** (preview) reloads the page, whose data layer then leads with the default. - [x] **`--no-analytics` and the event feed** (preview and built files). A kept `functional` script that subscribes ran once and was handed nothing across three page views. `subscribe()` gave back a function, called detached too; the data layer held each page view; there was no `window.gtag` and no Google tag. Without the flag the same script got all three. Run before `a895b2cd`: with the consent setting, such a build now queues the default and has a `window.gtag`. Since `b9450b72` the data layer holds no page view either (below). - [x] **`--no-analytics` and the data layer** (built files on `6792fa8d`, `googleConsentMode` set, a `necessary` script standing in for a tag manager that watches the data layer, and Google's own snippet listed as `functional`). After a fresh load, a page change and a search, the data layer holds the consent default, the snippet's own commands and Google's `gtm.dom` and `gtm.load`, and no `docs_` event. The stand-in saw no portal event, a subscriber got none, no cookie was set, and the snippet's page view was marked denied. - [x] **A host with a Content Security Policy** (built files at `94c58970`). With neither host in `script-src`, the listed address and Google's tag are refused, the listed file after them still runs and gets its events, and the theme switch and the in-app links work. With both hosts added, everything loads. - [x] **A real consent tool** (vanilla-cookieconsent 3.1.0, open source, listed in `portal.scripts` beside GA4 built in with `googleConsentMode`, and wired to Consent Mode as its guide shows; a preview at `94c58970`). On a first visit the banner is up, the portal's default leads the data layer, no cookie is set and the page view is marked denied. After "Accept all" the tool sends its update, the `_ga` cookies appear and the next hit is marked granted. On a return visit with the answer stored there is no banner, the update lands ahead of the first page view, and that page view is marked granted. Tag Assistant was not used: the hits themselves were read. - [x] **A real session recorder** (rrweb 2.0.0-alpha.4, listed in `portal.scripts`; the same preview). With the playground open, a number typed into its field is not in the recording, which holds a blocked placeholder for the dialog. A term typed into the search box is in it. This proves the `rr-block` marker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools. - [x] **Firefox and WebKit** (Playwright 1.64.1 on Windows: Firefox 157.0, and WebKit 27.2, the engine Safari uses; built files at `94c58970`). In both: the listed scripts sit in `<head>` in list order and not async; with the first served 1.5 s late, the files after it still ran after it; each ran once across four page views, one that removes its own tag included; a forwarder got every page view, and a late subscriber was handed all four; `subscribe` alone, frozen; the theme switch and in-app links work, with no error. - [x] **The renamed keys** (a preview with both renames, GA4 built in, every hit answered in the browser). A code copy, an SDK download and two searches, one closed and one with a pick, reach the data layer, a subscriber and GA4's own hits as `code_language`, `sdk_language` and `picked_result`. GA4's language field stays `en-us` on each. Before the rename a code copy set it to the code's language. - [x] **A heading called "gtag"** (built files; a preview does not show it, since its heading is not in the page when the script starts). Before `9a6e19b4`, on a fresh load of a guide with that heading: `window.gtag` is the heading, the console shows `a(...) is not a function`, search does not open, the theme switch does nothing, no listed script runs and no hit is sent. After it all of those work and the consent default leads the data layer. - [x] **A staging build that lists Google's own snippet** (built with `--no-analytics` on `ae99bcc1`, the snippet listed as `functional`, `googleConsentMode` set and no built-in tag). The data layer leads with the consent default, no cookie is set, the snippet's page view is marked denied, and a subscriber is handed nothing. - [x] **A script the host injects** (built files on `ae99bcc1`, the tag for a listed file added to one page's `<head>` by hand). It runs once and `<head>` holds one tag for it, on the fresh load and after two page changes. - [x] **A host's own object at `window.apimatic`** (same files, the object set before the portal's script). After the start it is the same object, its class's method works, and `subscribe` is there. A read-only `window.apimatic` holding an ordinary object gets `subscribe` too, with no error. - [x] **An address with a backslash for its host** (`portal generate` on `ae99bcc1`). Refused for a listed script and for `pluginUrl`, with the report that asks for a host; so is `https:///…`. A backslash in the path is accepted. - [x] **After the helpers were inlined** (built files on `665c8ef9`). The four checks above for `ae99bcc1` (a heading called "gtag", a script the host injects, a host's own object and a read-only `window.apimatic`, a staging build with Google's own snippet) and the data layer check for `6792fa8d` give the same results. - [x] **Config saves after `37db2b44`** (preview, on its tree). Saving a description reloads nothing and runs no script again, and the subscriber gets the next page view. Adding a script reloads the page with it, and a counter kept across the reload shows the added script ran once. - [x] **A config with no category** (`portal generate`, on the tree of `367cf0be`). It stops and reports `'portal.scripts[0].category' is required.` for the entry that names none, and the four choices for one that is misspelt. 🤖 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> Co-authored-by: Muhammad Rafay Nadeem <muhammad.nadeem@apimatic.io>



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
minimumReleaseAgeasks for. It is merged early by decision: see "Merged before the seven days".What a portal gets
********.0,falseand empty fields, and cookie parameters are sent as the specification says.?state=…loads them too, where it used to wait for the next page.What changes here
package.json:fumadocs-openapi12.6.5, andlucide-react1.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-upgrader0.4.8,@scalar/openapi-types0.9.9, and a new@scalar/helpers0.17.1).pnpm-workspace.yaml:@scalar/json-magicis held at 0.16.1 underfumadocs-openapi. 12.6.5 asks for 0.19, whose floor is Node 22.19, above the CLI's 22.14, so CI's--engine-strictinstall would refuse it. This is the same holdchokidarandundicialready 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, andholdsOAuthAnswer()andAnalytics.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.5turns 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:
pnpm dedupestops withERR_PNPM_NO_MATURE_MATCHING_VERSIONforfumadocs-openapi@12.6.5. A run that needs one addsfumadocs-openapi@12.6.5tominimumReleaseAgeExcludefor that run only.pnpm installandpnpm addwork as before.What speaks for the release:
After 23 Nov,
pnpm dedupe --checkshould pass without any exception. That is a check only: nothing in the lockfile needs to change.The lockfile here was resolved with a temporary
minimumReleaseAgeExcludeof five exact versions, which is not in this PR.A risk to know about
Because of the
@scalar/json-magichold, the tests in this repository run json-magic 0.16.1, while annpm install -gof 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 todev, 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.--engine-strict.In headless Chrome, on portals built from this branch with a neutral spec:
/oauth/callbackto 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.?state=CAloads its tags at once and is reported without the parameter.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:
EBADENGINEwarnings for@scalar/json-magic@0.19.1,chokidar@6.0.0,undici@8.12.4andundici@8.12.3. The first and the last are new with this PR: json-magic and the undici it pins.portal generatebuilds three portals: the layout reproduction, the OAuth one, and a specification with nested, shared and circular$refs across schemas, parameters, a request body and responses.portal serveworks: 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
zbsearch4.0.4 where the lockfile, ondevtoo, 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
After this merges
insertTags()and editsAnalytics.loadTags(), which this one removes. Whichever merges second resolves them:insertTags()keeps its new argument and the callback check, andloadTags()stays removed.?state=…loads no tag. Both lines change with this PR.Part of apimatic/apimatic-io#2350 (points 3 to 6).
🤖 Generated with Claude Code