Skip to content

feat(portal): load custom scripts from portal.scripts - #477

Open
sohail2721 wants to merge 25 commits into
devfrom
sohail/portal-scripts
Open

sohail2721 wants to merge 25 commits into
devfrom
sohail/portal-scripts

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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.

Ready for review. What is still to do before it merges is under "Before merging": the docs draft, the portal tests on this branch, and the decisions to record in the issues.

What a customer can now write

"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, and analytics when left out.
  • 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, and those with no category, along with the two Google tags. The scripts it keeps are handed no event: subscribe() is there and stays silent.
  • 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.

What is on the branch

One commit per step of the plan, then the fixes from two reviews, the merge with dev, and the two follow-ups to the second review.

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.
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.
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. subscribe() stays in place and silent, and the data layer gets its entries as before. 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. 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.

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 last four, which answer the review of 2026-11-17 and 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 feat(portal): load Google Tag Manager and GA4 from portal.analytics #473.
  • The flag's help is leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics', 'marketing' or not set, and hand no event to the scripts that stay. "The Google Tag Manager and Google Analytics tags" became "the tags", 5f1d49d9 added the scripts with no category, and 17ddf35f the events.
  • 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. The data layer still gets its entries: no vendor reads them there, and a preview's console can still show what would be 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, and a --no-analytics build queues nothing.

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.
  • 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 (fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #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. fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is a decision still to make. 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 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. Seen in a browser, for a read-only property and for one with a getter alone.
  • 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. Nothing here is released: #473 is on dev only, and this PR builds on it.

  • What changes for every portal, scripts listed or not:

    • The loader remembers the addresses it has inserted and no longer looks for them in <head>. This applies to the two Google tags too.
    • The mark of a started page, which feat(portal): load Google Tag Manager and GA4 from portal.analytics #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.eventFeed. A portal that sets no consent mode queues nothing new, and its feed is 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:///…) is now refused; the CLI used to accept it and write it without the extra slash.

    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 the default, window.apimatic.analytics.subscribe(), the event it hands over, 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. Its fourteen 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. None has had a code or security 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 and a browser run behind it, but no code or 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 feat(portal): load Google Tag Manager and GA4 from portal.analytics #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.
  • 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.
  • CI green on 310f38ab, the merge with dev: all 16 checks.
  • CI green on 07ee1f45, after the second review's fixes: all 16 checks.
  • CI green on 94c58970, the head: all 16 checks.
  • 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.
  • 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).
  • 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.
  • The docs draft gains the portal.scripts section, the new CLI row, and what the checks below measured. It is kept outside the PR, like feat(portal): load Google Tag Manager and GA4 from portal.analytics #473's. It also needs a consent section for googleConsentMode, and the flag's new wording.
  • 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.

  • tsc for the CLI, the tests and the template (the template's known errors from ungenerated files only).
  • 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/.
  • 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.
  • eslint ., the whole tree, as CI runs it after the tests: clean on 6ed31b30, on 07ee1f45 and on 94c58970.
  • APIMATIC_E2E=1 with test/e2e/portal-build.test.ts: 80 passing on 94c58970, 79 before the consent mode's test. APIMATIC_E2E=1 with test/e2e/portal-serve.test.ts: 6 passing.

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.

  • 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.
  • 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.
  • 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.
  • 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.
  • Categories. 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.
  • 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.
  • 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.
  • Through a config save. A subscriber from before a save that changed nothing got the next page view.
  • 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.
  • 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.
  • A script that fails (a host that does not resolve), first in the list: the next ones run, the page works.
  • A script that never answers, first and last in the list: see "Known limits".
  • Replay markers. A listed script with its own MutationObserver saw the playground dialog already carrying every marker.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • A GTM container (preview, GTM-KRV5DMCJ) with the setting: the default leads the data layer, no cookie is set, and hits are marked denied.
  • A config save that adds the setting (preview) reloads the page, whose data layer then leads with the default.
  • --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.
  • 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.
  • 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.
  • 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.
  • 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.
    🤖 Generated with Claude Code

Muhammad Sohail and others added 10 commits November 16, 2026 16:34
Each entry is { src }, an https address. The loader inserts them after
the vendor tags, in list order and not async, under the same hold on an
OAuth answer. The key a start runs once by covers the list, so a config
save under portal serve reloads with exactly the new one.

An inserted tag is now found by its src attribute as written: a selector
built from a customer's address misses on a backslash, and the script
would be inserted again on every page view.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A src that does not start with http: or https: names a file under
static/. It is checked on disk with the brand's files, written to the
identity file as its portal path, and inserted under the base path when
the portal is hosted under one.

A src that is neither an https address nor a file in static/ gets one
report naming both choices, since a path that is no file is often an
address without its https://.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…alytics

A listed script takes a category: necessary, functional, analytics or
marketing, and analytics when it names none. Under --no-analytics only
necessary and functional scripts reach the portal, for a build, a
preview and each config save alike.

PortalConfig.withoutVendors() is withoutAnalytics() now that it drops
more than the vendors, and the flag's help and the README say what it
leaves out.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pimatic

window.apimatic.analytics.subscribe(callback) hands a script every
event reported so far and then each new one, as a frozen
{ name, params, time, version: 1 }, and returns the function that
stops delivery. The feed is the page's, so a subscriber outlives the
second Analytics instance a config save under portal serve makes.

Earlier events arrive just after subscribe() returns, never inside
it, so a script can call the function it got back on the first event.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers scripts, with src as an
https address or a file in static/ and the four categories. The
address pattern pluginUrl had is one definition both settings use.

The schema test holds the schema and the parser to the same verdict
on each scripts case, and the schema's categories to the parser's
list.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now lists an address and a file from static/. The
built files have to hold both in a browser script, ship the file where
its address points, carry the feed scripts subscribe to, and name
neither script in a prerendered page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nter

The script set a property on window, which the whole-tree lint that runs
after the tests refuses in a file with no browser environment. The test
only checks that the file ships, so it now holds a comment and nothing
else.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed itself sat there. A script could publish events or empty the
history, subscribe threw when taken off the object and called on its
own, and an object a page had put at that name first made every report
throw.

Scripts now get a frozen object holding a bound subscribe, put in place
whatever was there before, and the feed is held at
window.portalEventFeed, where the reporter publishes to it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conventions leave a class with public methods and private static
helpers, and deliver() was a private instance method.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() listed every script in the head again for each tag and
listed script it wanted, on every page view. It now reads them once
into a set, which still keeps an address listed twice to one element.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sohail2721
sohail2721 marked this pull request as ready for review November 17, 2026 04:39
publish() copied the set before handing an event over, in case a
callback subscribed or unsubscribed meanwhile. The set's own iteration
already reaches one added in the same pass and skips one removed, and
deliver() checks a subscriber is still there, so the copy did nothing.
Two tests pin both cases.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
sohail2721 added a commit that referenced this pull request Nov 17, 2026
…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>
Muhammad Sohail and others added 9 commits November 17, 2026 12:41
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>
The feed called a callback as a method of the record it keeps for that
subscriber, so a callback written without strict mode got the record as
`this`. Writing to it could reset the count delivery runs on, which
handed the same event over without end, and a callback that expected
the window there kept its state in the record instead.

A callback is now called on its own, as any function is.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed sat at window.portalEventFeed, beside the mark of what the
page started with. Both showed among the window's own names, and the
feed there offered publish() to any script that came across it.

The window now holds both under one key, a symbol, so it gains no name
but apimatic and the data layer. A script that looks for the feed can
still reach it, as it can anything on the page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() took the head as its record of what it had inserted. A
vendor's loader that removes its own element once it has run was
inserted again on the next page view, so it ran twice on the first
page and once more for every page after.

The page now remembers each address it inserted, for a second instance
under portal serve too, and no page view reads the head.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The start runs while the bundle loads, and it assigned to
window.apimatic. Where a host had locked that name the assignment
threw, the bundle stopped, and the page never came to life: no search,
no theme switch, no listed script and no tag.

The portal now starts all the same and shows the error in the console
a moment later. Scripts on such a page get no subscribe().

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The parser took https:///cdn.example.com/widget.js and wrote the
address without the extra slash, while the schema marked it wrong in an
editor. httpsAddress() now holds an address to the schema's pattern,
for pluginUrl as for a script, and parses it once.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Script.staticFile() answered null for an address, which its caller had
to filter out. It is staticFiles() now and answers a list, empty for an
address.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A script that names no category counts as analytics, so the flag leaves
it out, but the flag's help and the README named only the analytics and
marketing scripts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
deliveredCount and an Unsubscribe type replace the comments on the
feed's count and on what subscribe() returns, and a two-line comment in
the schema test is one line.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sohail2721 sohail2721 mentioned this pull request Nov 17, 2026
Muhammad Sohail and others added 4 commits November 17, 2026 15:02
The description of portal.scripts still said they load once the address
holds no OAuth answer. Since the merge with dev they load on every page
but the OAuth callback.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A build made with --no-analytics left out the tags and the analytics
and marketing scripts, and still handed every event, a reader's search
terms among them, to the necessary and functional scripts it kept.

The identity file now says whether the event feed is on, and it is off
for such a build. subscribe() stays in place there and is handed
nothing, so a kept script that calls it does not throw. The data layer
gets its entries as before. The flag's help says what changed.

AnalyticsConfig.withoutVendors() is withoutAnalytics() now that it
turns off more than the vendors.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A consent tool listed in portal.scripts could lose a race with the
built-in Google tags: when it arrived after Google's library, cookies
were set and the page view was sent before it had said "denied".

portal.analytics.googleConsentMode, { "default": "denied" }, makes the
portal queue Google's consent defaults itself, before it sets either
tag up: the four Consent Mode v2 types denied, and a wait of 500 ms for
a consent tool to hand over a returning reader's answer. Both tags load
as before, and set no cookie until something on the page calls
gtag('consent', 'update'). A build made with --no-analytics queues
nothing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers googleConsentMode, with
default required and "denied" its one value. The schema test holds the
schema and the parser to the same verdict on each case.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now sets googleConsentMode. A browser script has to
hold the setting and the defaults it queues, and no prerendered page
may hold them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant