Skip to content

Release 2.3.0-beta.2 - #482

Merged
sohail2721 merged 3 commits into
betafrom
dev
Nov 19, 2026
Merged

sohail2721 merged 3 commits into
betafrom
dev

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Promotes dev to beta. This should publish 2.3.0-beta.2 to the npm beta dist-tag as a GitHub prerelease. The release run commits nothing back to beta; the tag goes on this PR's merge commit. dev already contains main's 2.2.0 merge, so the version continues from v2.3.0-beta.1.

Merge with Create a merge commit.

What releases

Everything on dev since 2.3.0-beta.1: one feat and one fix, with nothing marked !. That makes it the next prerelease of 2.3.0:

#480 is a docs commit, so it's in the build but stays out of the notes. It changes the --no-analytics help to say the flag sends no events to the scripts it keeps, the wording apimatic/apimatic-docs#887 uses.

With this beta, portal.analytics (out in 2.3.0-beta.1) and portal.scripts are both released, as apimatic/apimatic-io#2347 plans for a single release.

Changes for users of 2.3.0-beta.1

#477 renames three event parameters. Anyone who set up GA4 custom definitions or Google Tag Manager variables on beta.1 needs the new names:

Event 2.3.0-beta.1 2.3.0-beta.2
docs_code_copy language code_language
docs_sdk_download language sdk_language
docs_search result picked_result

Before this beta goes to main

The portal automation tests passed on dev at 49480d3b, this PR's head.

🤖 Generated with Claude Code

sohail2721 and others added 2 commits November 19, 2026 10:13
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>
…change it (#481)

Fixes the bug in the QA report apimatic/apimatic-io#2357. When a custom
script added an element to the portal's header or to a page, the element
was lost and the whole page was rebuilt.

## Why

The portal inserted the scripts listed in `portal.scripts` as soon as
its own code started, before React had hydrated the prerendered page. A
script that added an element inside the page made hydration fail with
React error #418. React then threw the whole prerendered page away and
built it again in the browser, without the element. An element added to
`<body>` survived, because React skips unknown nodes there.

The problem is in the portal's own code, not in Fumadocs. Our loader
decided when the scripts ran, and any element React renders breaks the
same way, not only the Fumadocs header.

## The change

The Google tags and the consent default still start immediately. The
listed scripts now wait until React has hydrated the page.

- `analytics.ts`: `start()` and `reportPageView()` insert only the
Google tags. A new `loadScripts()` inserts the listed scripts, each
once, as before.
- `components/listed-scripts.tsx`: a new component that renders nothing
and calls `analytics.loadScripts()` from its effect.
- `routes/$.tsx`: one `<Suspense>` now holds every kind of page's
content, together with `ListedScripts`. Before, only a Markdown page's
content had one.
- React hydrates the root first, then each Suspense boundary in a later
pass, and the content's boundary comes last. So the effect runs only
once the whole page is hydrated.
- A boundary of its own for `ListedScripts` wasn't enough. It finished
first whenever the content was still waiting for its chunk, and 2 runs
in 5 still failed.
- `components/not-found.tsx`: renders `ListedScripts` too.

## What changes for a script

- **Later start:** a script runs once the page is hydrated. On a guide
page that is about 205 ms after navigation instead of about 140 ms, and
about 1.3 s instead of about 0.8 s with the CPU slowed six times.
- **Consent tools:** with `googleConsentMode` set, the Google tags still
start as denied. A consent tool listed in `portal.scripts` runs later by
the same amount. On a slow device, a returning reader's first hit can go
out as denied before the tool reports their answer, because the consent
default waits 500 ms for it.
- **Moving between pages:** an element added to the header or sidebar
stays as the reader moves between pages. One added inside a page's
content stays on the next guide page and is gone on an API reference
page.

## Tests

- `test/portal-template/analytics.test.ts`: the listed-script tests call
`loadScripts()` after `start()`. A new test pins that neither a start
nor a page view inserts a listed script, and that `loadScripts()`
inserts all of them.
- That file and `test/portal-template/event-feed.test.ts`: 109 passing.
- `APIMATIC_E2E=1`: `test/e2e/portal-build.test.ts` 81 passing,
`test/e2e/portal-serve.test.ts` 6 passing.

## Checked in a browser

All in headless Chrome, on portals built from this branch and served the
way a static host serves them, and under `portal serve`.

- **The #2357 repro:** a listed file adds an element to the header, the
sidebar, the article and `<body>` when it runs.
- Before this change: React error #418 in every run, and every
prerendered node under `<body>` was replaced.
- After: no #418 in any of 8 runs: a guide page 3 times, a guide page
twice with the CPU slowed six times, an API reference page and the home
page slowed six times, and the not-found page. All four elements and
every prerendered node stay. It passes under `portal serve` too.
- **The checks from #477, run again:**
- Listed scripts run in list order, once per page load, and not again on
client-side moves. An address listed twice loads once.
  - Under `/docs`, files load from `/docs/js/…`.
- `subscribe()` replays the first page view to a listed script, delivers
live events, freezes them, unsubscribes, and throws a `TypeError` for a
non-function.
  - `/oauth/callback` loads no script and no tag.
- `--no-analytics` leaves out `analytics` and `marketing` scripts and
sends no events.
- A script the host already put in `<head>` downloads once, and the
host's own object at `window.apimatic` is kept.
- Under `portal serve`, four config saves each reload the page once with
exactly the new list.
- No uncaught errors. The not-found page still logs the deliberate
"Falling back to the not-found page" message from `routes/$.tsx`.

## Not covered

- **The API playground:** it hydrates in Suspense boundaries of its own,
which can finish after the scripts load. A script that changes the
playground itself wasn't tried.
- **Google Tag Manager:** its tags still start immediately, so a Custom
HTML tag that changes the page early isn't covered by this change.

## Docs

apimatic/apimatic-docs#887 (`da17d7aa`) changes Add Custom Scripts:
- The portal adds the scripts once the page is ready.
- What happens to an element a script adds as the reader moves between
pages.
- A script that never answers can delay the `load` event, rather than
always delaying it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…stay (#480)

The `--no-analytics` help for `portal generate` and `portal serve` said
the flag would "hand no event to the scripts that stay", which took a
second read. It now says "send no events", in the flag's help and the
README.

The docs say the same since apimatic/apimatic-docs#887: the CLI
Reference rows, Add Custom Scripts and the changelog. This keeps the
help text and the docs in step before the release that ships #473 and
#477.

Only the wording changes. Typecheck, the portal command flag tests and
`eslint .` pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

@sohail2721
sohail2721 merged commit 3e5cb1a into beta Nov 19, 2026
17 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

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

The release is available on:

Your semantic-release bot 📦🚀

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants