@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/internal-traffic.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The GA4 event parameter GA's built-in internal-traffic data filter matches
+ * on, and the value its default rule uses.
+ *
+ * Named here rather than inlined because the strings have to agree with a
+ * setting in the GA UI that nothing in this repo can typecheck against — see
+ * `docs/ANALYTICS.md` §8 — and because THREE surfaces now stamp them: the
+ * console through Firebase's `setDefaultEventParameters`, the tenant runtime
+ * and the docs site through a raw `gtag('set', …)`. One definition is what
+ * keeps the console's parameter and the marketing site's parameter the same
+ * parameter; two spellings would read as two dimensions in GA and the filter
+ * would catch one of them.
+ */
+export declare const INTERNAL_TRAFFIC_PARAM = "traffic_type";
+export declare const INTERNAL_TRAFFIC_VALUE = "internal";
+/**
+ * Where a browser's opt-in is remembered, and the query parameter that sets
+ * it (AGL-2064 / AGL-2065).
+ *
+ * ## Why an explicit override exists at all
+ *
+ * The AGL-1582 predicate keys on ID-token claims — `staff` or `impersonatedBy`
+ * — which is right, and insufficient. Several release drills REQUIRE a
+ * non-staff account: the marketplace publisher drill cannot be run by staff at
+ * all, because the thing being exercised is a publisher installing their own
+ * unreviewed version. Those sessions emit `sign_up`, `org_created`,
+ * `host_created`, `site_published` and `begin_checkout` — precisely the
+ * activation and revenue events the September funnel is read from — and the
+ * claims predicate correctly declines to flag them.
+ *
+ * Widening the predicate would be the wrong repair. It would flag by identity,
+ * and a customer identity is the point of the drill. So the override is a
+ * property of the BROWSER, not of the account: a browser we have declared to
+ * be ours stays ours across sign-outs, re-auths and whichever test account is
+ * currently signed in.
+ *
+ * And the marketing surface has no account to consult in the first place —
+ * `aglyn.com`, `/pricing` and every published site are browsed logged out,
+ * which is why that leak is the larger one and why this is the only mechanism
+ * that can close it.
+ *
+ * ## Why `localStorage`, and what being origin-scoped costs
+ *
+ * It has to survive a reload and a full page navigation, which rules out
+ * module state, and it has to be readable by an inline script before the tag
+ * library loads, which rules out anything asynchronous. `localStorage` is
+ * both, and it was deliberately NOT a cookie: a cookie rides to the server on
+ * every request and ends up in logs.
+ *
+ * ## Why a cookie now rides ALONGSIDE it (AGL-3175)
+ *
+ * That reasoning held while the surfaces were a fixed list. They are not. The
+ * console is served on every `*.aglyn.com` hostname, and `WORKSPACE_DOMAIN` is
+ * `aglyn.com`, so EVERY ORG WORKSPACE IS ITS OWN ORIGIN — fourteen distinct
+ * hostnames have sent events to the property, among them generated slugs like
+ * `34kwy7hnbr`. Per-origin storage cannot be opted into on a hostname that
+ * does not exist yet, so the opt-in list was not merely incomplete, it was
+ * uncompletable. `auth.aglyn.com` sat unpinned for a month on exactly that.
+ *
+ * So the opt-in is ALSO written as a cookie scoped to the workspace domain,
+ * and either source turning it on is enough. What the cookie costs is what the
+ * paragraph above says it costs: the constant string `internal` now appears in
+ * request headers to our own hosts. It carries no identity — it says "this
+ * browser is ours" and nothing about who is using it — and it rides beside
+ * `__session`, which the same domain already carries.
+ *
+ * ## What still bounds it
+ *
+ * The cookie is written ONLY where a call site passes `cookieDomain`, and the
+ * console's helper passes it only when the current hostname is under that
+ * domain. Nothing here writes a cookie on a customer's custom domain, and
+ * nothing needs to: published sites are on `aglyn.app` and custom domains,
+ * which a `.aglyn.com` cookie cannot reach. That registrable-domain boundary
+ * — not per-origin storage — is what keeps an opt-in on our console out of a
+ * CUSTOMER's Analytics property while we click through their published site.
+ *
+ * `INTERNAL_TRAFFIC_GTAG_SNIPPET` is deliberately left on storage alone. It is
+ * a constant string inlined into ISR-cached customer HTML (with a verbatim
+ * copy in the docs site's config), it cannot be made hostname-aware, and every
+ * surface that uses it is a fixed origin that can be pinned directly.
+ *
+ * ## Bias
+ *
+ * Opt-in only, never inferred. Wrongly flagging a real customer erases them
+ * from every report and a GA4 data filter is not retroactive, so every
+ * ambiguous case here resolves to "not internal".
+ */
+export declare const INTERNAL_TRAFFIC_STORAGE_KEY = "aglyn_traffic_type";
+export declare const INTERNAL_TRAFFIC_QUERY_PARAM = "aglyn_internal";
+/**
+ * The cookie that carries the same opt-in across every origin under one
+ * domain. Same name as the storage key on purpose: one concept, and a browser
+ * inspector shows the two halves of it side by side under one label.
+ */
+export declare const INTERNAL_TRAFFIC_COOKIE_KEY = "aglyn_traffic_type";
+/** The browser bits `readInternalTrafficOverride` needs, so a test can supply them. */
+export interface InternalTrafficOverrideSource {
+    /** `window.location.search`, leading `?` optional. */
+    search?: string | null;
+    /** `window.localStorage`, or null where the browser refuses one. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** `document.cookie`, for the READ half. Absent means no cookie source. */
+    cookie?: string | null;
+    /**
+     * The domain to scope the cookie WRITE to, bare (`aglyn.com`). Absent means
+     * this call site does not write cookies at all, which is the default and
+     * what every shared caller does — see the module comment. Only a call site
+     * that has already established it is on a first-party host passes it.
+     */
+    cookieDomain?: string | null;
+    /** Where a written cookie goes. Defaults to `document.cookie`. */
+    writeCookie?: ((serialized: string) => void) | null;
+}
+/**
+ * Whether THIS BROWSER has been declared one of ours, applying `?aglyn_internal`
+ * first if it is on the URL.
+ *
+ * Reading and writing in one call is deliberate: the query parameter has to
+ * take effect on the pageview that carries it, not on the next one, because
+ * the pageview that carries it is already a hit. Persisting it here is what
+ * makes the single `?aglyn_internal=1` visit enough.
+ *
+ * Never throws. A browser with `localStorage` disabled, a sandboxed iframe and
+ * a server render all resolve to `false` — the not-internal direction, which
+ * is the safe one.
+ */
+export declare function readInternalTrafficOverride(source?: InternalTrafficOverrideSource): boolean;
+/**
+ * The override, pinned domain-wide rather than per origin (AGL-3175).
+ *
+ * For the console, which is the surface served on an open-ended set of
+ * `*.aglyn.com` origins. The hostname check is the gate the module comment
+ * describes: it is what guarantees no cookie is ever written on a customer's
+ * custom domain, and it also keeps `localhost` and preview deployments — where
+ * a `Secure` cookie for another domain would be rejected anyway — writing
+ * nothing but `localStorage`, exactly as before.
+ */
+export declare function readInternalTrafficOverrideForDomain(domain: string | null | undefined): boolean;
+/**
+ * The same decision as `readInternalTrafficOverride`, as a CONSTANT string of
+ * JavaScript, for the surfaces that drive gtag directly (AGL-2064).
+ *
+ * ## Why a string, and why it must stay constant
+ *
+ * The tenant runtime serves ISR-cached HTML: one cached document is handed to
+ * every visitor, so nothing about this decision may be made while rendering.
+ * A server-side branch would bake one browser's answer into the cache for
+ * everyone, and a first-client-render branch would break hydration. Emitting
+ * the same bytes to everyone and letting them decide AT RUNTIME, in the
+ * browser, is the only shape that is both correct and cacheable — the same
+ * move `consent.ready` makes one layer up.
+ *
+ * ## Why it must run before `gtag('config', …)`
+ *
+ * GA4's internal-traffic filter matches per EVENT, and the events that leak
+ * are the ones no call site writes: `session_start`, `first_visit`,
+ * `user_engagement` and the automatic `page_view`. A `gtag('set', …)` applies
+ * to every hit gtag processes AFTER it in queue order, so placed between the
+ * `dataLayer` shim and the `config` call it rides all of them. Placed after
+ * `config` it would miss the session's first pageview — which is the whole
+ * session, for a marketing visit.
+ *
+ * ## Safe to inline
+ *
+ * No interpolation, so nothing can inject; contains no `<` at all, so it
+ * cannot close its own `<script>` element. It assumes only that a `gtag`
+ * function is already defined, which is the line immediately above it in every
+ * call site.
+ */
+export declare const INTERNAL_TRAFFIC_GTAG_SNIPPET: string;
+/**
+ * The stamp with no opt-in check at all, for a build that has already decided
+ * every one of its hits is ours (AGL-2067).
+ *
+ * Used only where `analyticsEnvironmentForcesInternal()` holds: a
+ * non-production build running with the analytics escape hatch on. Nobody
+ * reaches that state by accident, so consulting the browser as well would only
+ * create a way for it to be wrong.
+ */
+export declare const INTERNAL_TRAFFIC_FORCED_SNIPPET = "gtag('set',{'traffic_type':'internal'});";
+export default readInternalTrafficOverride;

package/src/lib/app-utils/internal-traffic.js

@@ -0,0 +1,288 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The GA4 event parameter GA's built-in internal-traffic data filter matches
+ * on, and the value its default rule uses.
+ *
+ * Named here rather than inlined because the strings have to agree with a
+ * setting in the GA UI that nothing in this repo can typecheck against — see
+ * `docs/ANALYTICS.md` §8 — and because THREE surfaces now stamp them: the
+ * console through Firebase's `setDefaultEventParameters`, the tenant runtime
+ * and the docs site through a raw `gtag('set', …)`. One definition is what
+ * keeps the console's parameter and the marketing site's parameter the same
+ * parameter; two spellings would read as two dimensions in GA and the filter
+ * would catch one of them.
+ */ export const INTERNAL_TRAFFIC_PARAM = 'traffic_type';
+export const INTERNAL_TRAFFIC_VALUE = 'internal';
+/**
+ * Where a browser's opt-in is remembered, and the query parameter that sets
+ * it (AGL-2064 / AGL-2065).
+ *
+ * ## Why an explicit override exists at all
+ *
+ * The AGL-1582 predicate keys on ID-token claims — `staff` or `impersonatedBy`
+ * — which is right, and insufficient. Several release drills REQUIRE a
+ * non-staff account: the marketplace publisher drill cannot be run by staff at
+ * all, because the thing being exercised is a publisher installing their own
+ * unreviewed version. Those sessions emit `sign_up`, `org_created`,
+ * `host_created`, `site_published` and `begin_checkout` — precisely the
+ * activation and revenue events the September funnel is read from — and the
+ * claims predicate correctly declines to flag them.
+ *
+ * Widening the predicate would be the wrong repair. It would flag by identity,
+ * and a customer identity is the point of the drill. So the override is a
+ * property of the BROWSER, not of the account: a browser we have declared to
+ * be ours stays ours across sign-outs, re-auths and whichever test account is
+ * currently signed in.
+ *
+ * And the marketing surface has no account to consult in the first place —
+ * `aglyn.com`, `/pricing` and every published site are browsed logged out,
+ * which is why that leak is the larger one and why this is the only mechanism
+ * that can close it.
+ *
+ * ## Why `localStorage`, and what being origin-scoped costs
+ *
+ * It has to survive a reload and a full page navigation, which rules out
+ * module state, and it has to be readable by an inline script before the tag
+ * library loads, which rules out anything asynchronous. `localStorage` is
+ * both, and it was deliberately NOT a cookie: a cookie rides to the server on
+ * every request and ends up in logs.
+ *
+ * ## Why a cookie now rides ALONGSIDE it (AGL-3175)
+ *
+ * That reasoning held while the surfaces were a fixed list. They are not. The
+ * console is served on every `*.aglyn.com` hostname, and `WORKSPACE_DOMAIN` is
+ * `aglyn.com`, so EVERY ORG WORKSPACE IS ITS OWN ORIGIN — fourteen distinct
+ * hostnames have sent events to the property, among them generated slugs like
+ * `34kwy7hnbr`. Per-origin storage cannot be opted into on a hostname that
+ * does not exist yet, so the opt-in list was not merely incomplete, it was
+ * uncompletable. `auth.aglyn.com` sat unpinned for a month on exactly that.
+ *
+ * So the opt-in is ALSO written as a cookie scoped to the workspace domain,
+ * and either source turning it on is enough. What the cookie costs is what the
+ * paragraph above says it costs: the constant string `internal` now appears in
+ * request headers to our own hosts. It carries no identity — it says "this
+ * browser is ours" and nothing about who is using it — and it rides beside
+ * `__session`, which the same domain already carries.
+ *
+ * ## What still bounds it
+ *
+ * The cookie is written ONLY where a call site passes `cookieDomain`, and the
+ * console's helper passes it only when the current hostname is under that
+ * domain. Nothing here writes a cookie on a customer's custom domain, and
+ * nothing needs to: published sites are on `aglyn.app` and custom domains,
+ * which a `.aglyn.com` cookie cannot reach. That registrable-domain boundary
+ * — not per-origin storage — is what keeps an opt-in on our console out of a
+ * CUSTOMER's Analytics property while we click through their published site.
+ *
+ * `INTERNAL_TRAFFIC_GTAG_SNIPPET` is deliberately left on storage alone. It is
+ * a constant string inlined into ISR-cached customer HTML (with a verbatim
+ * copy in the docs site's config), it cannot be made hostname-aware, and every
+ * surface that uses it is a fixed origin that can be pinned directly.
+ *
+ * ## Bias
+ *
+ * Opt-in only, never inferred. Wrongly flagging a real customer erases them
+ * from every report and a GA4 data filter is not retroactive, so every
+ * ambiguous case here resolves to "not internal".
+ */ export const INTERNAL_TRAFFIC_STORAGE_KEY = 'aglyn_traffic_type';
+export const INTERNAL_TRAFFIC_QUERY_PARAM = 'aglyn_internal';
+/**
+ * The cookie that carries the same opt-in across every origin under one
+ * domain. Same name as the storage key on purpose: one concept, and a browser
+ * inspector shows the two halves of it side by side under one label.
+ */ export const INTERNAL_TRAFFIC_COOKIE_KEY = 'aglyn_traffic_type';
+/**
+ * 400 days, which is the ceiling Chrome clamps `Max-Age` to anyway. Expiry is
+ * not a feature here — the opt-in is meant to be permanent, and a browser that
+ * quietly forgets it puts our own browsing back into the launch metrics, which
+ * a GA4 data filter cannot undo after the fact.
+ */ const INTERNAL_TRAFFIC_COOKIE_MAX_AGE = 34560000;
+/**
+ * The values of `?aglyn_internal=` that turn the override OFF again. Anything
+ * else present turns it on, so `?aglyn_internal` with no value works — that is
+ * the form someone types from memory.
+ */ const OFF_VALUES = new Set([
+    '0',
+    'false',
+    'off',
+    'no'
+]);
+/** Whether a `document.cookie` string carries our opt-in. Never throws. */ function cookieSaysInternal(cookie) {
+    if (!cookie) return false;
+    for (const part of cookie.split(';')){
+        const eq = part.indexOf('=');
+        if (eq < 0) continue;
+        if (part.slice(0, eq).trim() !== INTERNAL_TRAFFIC_COOKIE_KEY) continue;
+        return part.slice(eq + 1).trim() === INTERNAL_TRAFFIC_VALUE;
+    }
+    return false;
+}
+/**
+ * Mirror the opt-in into the domain-wide cookie, when the call site asked for
+ * it. A no-op everywhere else, which is every shared caller.
+ *
+ * `SameSite=Lax` and `Secure` because this rides to our own hosts and has no
+ * cross-site job; clearing writes the same attributes with `Max-Age=0`,
+ * because a cookie is only replaced by one whose domain and path match.
+ */ function writeInternalTrafficCookie(source, on) {
+    var _source_writeCookie;
+    const domain = source.cookieDomain;
+    if (!domain) return;
+    const write = (_source_writeCookie = source.writeCookie) != null ? _source_writeCookie : typeof document === 'undefined' ? null : (serialized)=>{
+        document.cookie = serialized;
+    };
+    if (!write) return;
+    try {
+        write(`${INTERNAL_TRAFFIC_COOKIE_KEY}=${on ? INTERNAL_TRAFFIC_VALUE : ''}` + `; Domain=.${domain}; Path=/; SameSite=Lax; Secure` + `; Max-Age=${on ? INTERNAL_TRAFFIC_COOKIE_MAX_AGE : 0}`);
+    } catch (unused) {
+    // A refused cookie jar leaves `localStorage` holding the opt-in for this
+    // origin, which is where it lived before this existed.
+    }
+}
+/**
+ * Whether THIS BROWSER has been declared one of ours, applying `?aglyn_internal`
+ * first if it is on the URL.
+ *
+ * Reading and writing in one call is deliberate: the query parameter has to
+ * take effect on the pageview that carries it, not on the next one, because
+ * the pageview that carries it is already a hit. Persisting it here is what
+ * makes the single `?aglyn_internal=1` visit enough.
+ *
+ * Never throws. A browser with `localStorage` disabled, a sandboxed iframe and
+ * a server render all resolve to `false` — the not-internal direction, which
+ * is the safe one.
+ */ export function readInternalTrafficOverride(source) {
+    var _window_location;
+    const resolved = source != null ? source : typeof window === 'undefined' ? {} : {
+        search: (_window_location = window.location) == null ? void 0 : _window_location.search,
+        storage: safeLocalStorage(),
+        cookie: safeDocumentCookie()
+    };
+    const storage = resolved.storage;
+    // Read the cookie BEFORE the storage gate. A browser that refuses
+    // `localStorage` outright — Safari private mode, a partitioned frame — can
+    // still be one of ours, and before AGL-3175 that browser was unpinnable.
+    let cookieOn = cookieSaysInternal(resolved.cookie);
+    if (!storage) return cookieOn;
+    try {
+        const search = resolved.search;
+        if (search) {
+            const requested = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search).get(INTERNAL_TRAFFIC_QUERY_PARAM);
+            if (requested !== null) {
+                // Both halves move together, so `?aglyn_internal=0` really is an
+                // off switch: clearing storage while the cookie still said `internal`
+                // would leave the browser pinned with nothing local to show for it.
+                if (OFF_VALUES.has(requested.toLowerCase())) {
+                    storage.removeItem(INTERNAL_TRAFFIC_STORAGE_KEY);
+                    writeInternalTrafficCookie(resolved, false);
+                    cookieOn = false;
+                } else {
+                    storage.setItem(INTERNAL_TRAFFIC_STORAGE_KEY, INTERNAL_TRAFFIC_VALUE);
+                    writeInternalTrafficCookie(resolved, true);
+                    cookieOn = true;
+                }
+            }
+        }
+        return cookieOn || storage.getItem(INTERNAL_TRAFFIC_STORAGE_KEY) === INTERNAL_TRAFFIC_VALUE;
+    } catch (unused) {
+        // Storage access can throw outright (Safari private mode, a partitioned
+        // third-party context). The cookie is the other half and may still answer.
+        return cookieOn;
+    }
+}
+/** `document.cookie` where reaching for it does not throw, else null. */ function safeDocumentCookie() {
+    try {
+        return typeof document === 'undefined' ? null : document.cookie;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The override, pinned domain-wide rather than per origin (AGL-3175).
+ *
+ * For the console, which is the surface served on an open-ended set of
+ * `*.aglyn.com` origins. The hostname check is the gate the module comment
+ * describes: it is what guarantees no cookie is ever written on a customer's
+ * custom domain, and it also keeps `localhost` and preview deployments — where
+ * a `Secure` cookie for another domain would be rejected anyway — writing
+ * nothing but `localStorage`, exactly as before.
+ */ export function readInternalTrafficOverrideForDomain(domain) {
+    var _ref;
+    var _window_location, _window_location1;
+    if (typeof window === 'undefined') return false;
+    const host = (_ref = (_window_location = window.location) == null ? void 0 : _window_location.hostname) != null ? _ref : '';
+    const underDomain = !!domain && (host === domain || host.endsWith(`.${domain}`));
+    return readInternalTrafficOverride({
+        search: (_window_location1 = window.location) == null ? void 0 : _window_location1.search,
+        storage: safeLocalStorage(),
+        cookie: safeDocumentCookie(),
+        cookieDomain: underDomain ? domain : null
+    });
+}
+/** `window.localStorage` where reaching for it does not throw, else null. */ function safeLocalStorage() {
+    try {
+        var _window_localStorage;
+        return (_window_localStorage = window.localStorage) != null ? _window_localStorage : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The same decision as `readInternalTrafficOverride`, as a CONSTANT string of
+ * JavaScript, for the surfaces that drive gtag directly (AGL-2064).
+ *
+ * ## Why a string, and why it must stay constant
+ *
+ * The tenant runtime serves ISR-cached HTML: one cached document is handed to
+ * every visitor, so nothing about this decision may be made while rendering.
+ * A server-side branch would bake one browser's answer into the cache for
+ * everyone, and a first-client-render branch would break hydration. Emitting
+ * the same bytes to everyone and letting them decide AT RUNTIME, in the
+ * browser, is the only shape that is both correct and cacheable — the same
+ * move `consent.ready` makes one layer up.
+ *
+ * ## Why it must run before `gtag('config', …)`
+ *
+ * GA4's internal-traffic filter matches per EVENT, and the events that leak
+ * are the ones no call site writes: `session_start`, `first_visit`,
+ * `user_engagement` and the automatic `page_view`. A `gtag('set', …)` applies
+ * to every hit gtag processes AFTER it in queue order, so placed between the
+ * `dataLayer` shim and the `config` call it rides all of them. Placed after
+ * `config` it would miss the session's first pageview — which is the whole
+ * session, for a marketing visit.
+ *
+ * ## Safe to inline
+ *
+ * No interpolation, so nothing can inject; contains no `<` at all, so it
+ * cannot close its own `<script>` element. It assumes only that a `gtag`
+ * function is already defined, which is the line immediately above it in every
+ * call site.
+ */ export const INTERNAL_TRAFFIC_GTAG_SNIPPET = 'try{' + `var aq=new URLSearchParams(location.search).get('${INTERNAL_TRAFFIC_QUERY_PARAM}');` + 'if(aq!==null){' + `if(['${[
+    ...OFF_VALUES
+].join("','")}'].indexOf(aq.toLowerCase())>=0)` + `localStorage.removeItem('${INTERNAL_TRAFFIC_STORAGE_KEY}');` + `else localStorage.setItem('${INTERNAL_TRAFFIC_STORAGE_KEY}','${INTERNAL_TRAFFIC_VALUE}');` + '}' + `if(localStorage.getItem('${INTERNAL_TRAFFIC_STORAGE_KEY}')==='${INTERNAL_TRAFFIC_VALUE}')` + `gtag('set',{'${INTERNAL_TRAFFIC_PARAM}':'${INTERNAL_TRAFFIC_VALUE}'});` + '}catch(e){}';
+/**
+ * The stamp with no opt-in check at all, for a build that has already decided
+ * every one of its hits is ours (AGL-2067).
+ *
+ * Used only where `analyticsEnvironmentForcesInternal()` holds: a
+ * non-production build running with the analytics escape hatch on. Nobody
+ * reaches that state by accident, so consulting the browser as well would only
+ * create a way for it to be wrong.
+ */ export const INTERNAL_TRAFFIC_FORCED_SNIPPET = `gtag('set',{'${INTERNAL_TRAFFIC_PARAM}':'${INTERNAL_TRAFFIC_VALUE}'});`;
+export default readInternalTrafficOverride;
+
+//# sourceMappingURL=internal-traffic.js.map

package/src/lib/app-utils/internal-traffic.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/internal-traffic.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The GA4 event parameter GA's built-in internal-traffic data filter matches\n * on, and the value its default rule uses.\n *\n * Named here rather than inlined because the strings have to agree with a\n * setting in the GA UI that nothing in this repo can typecheck against — see\n * `docs/ANALYTICS.md` §8 — and because THREE surfaces now stamp them: the\n * console through Firebase's `setDefaultEventParameters`, the tenant runtime\n * and the docs site through a raw `gtag('set', …)`. One definition is what\n * keeps the console's parameter and the marketing site's parameter the same\n * parameter; two spellings would read as two dimensions in GA and the filter\n * would catch one of them.\n */\nexport const INTERNAL_TRAFFIC_PARAM = 'traffic_type'\nexport const INTERNAL_TRAFFIC_VALUE = 'internal'\n\n/**\n * Where a browser's opt-in is remembered, and the query parameter that sets\n * it (AGL-2064 / AGL-2065).\n *\n * ## Why an explicit override exists at all\n *\n * The AGL-1582 predicate keys on ID-token claims — `staff` or `impersonatedBy`\n * — which is right, and insufficient. Several release drills REQUIRE a\n * non-staff account: the marketplace publisher drill cannot be run by staff at\n * all, because the thing being exercised is a publisher installing their own\n * unreviewed version. Those sessions emit `sign_up`, `org_created`,\n * `host_created`, `site_published` and `begin_checkout` — precisely the\n * activation and revenue events the September funnel is read from — and the\n * claims predicate correctly declines to flag them.\n *\n * Widening the predicate would be the wrong repair. It would flag by identity,\n * and a customer identity is the point of the drill. So the override is a\n * property of the BROWSER, not of the account: a browser we have declared to\n * be ours stays ours across sign-outs, re-auths and whichever test account is\n * currently signed in.\n *\n * And the marketing surface has no account to consult in the first place —\n * `aglyn.com`, `/pricing` and every published site are browsed logged out,\n * which is why that leak is the larger one and why this is the only mechanism\n * that can close it.\n *\n * ## Why `localStorage`, and what being origin-scoped costs\n *\n * It has to survive a reload and a full page navigation, which rules out\n * module state, and it has to be readable by an inline script before the tag\n * library loads, which rules out anything asynchronous. `localStorage` is\n * both, and it was deliberately NOT a cookie: a cookie rides to the server on\n * every request and ends up in logs.\n *\n * ## Why a cookie now rides ALONGSIDE it (AGL-3175)\n *\n * That reasoning held while the surfaces were a fixed list. They are not. The\n * console is served on every `*.aglyn.com` hostname, and `WORKSPACE_DOMAIN` is\n * `aglyn.com`, so EVERY ORG WORKSPACE IS ITS OWN ORIGIN — fourteen distinct\n * hostnames have sent events to the property, among them generated slugs like\n * `34kwy7hnbr`. Per-origin storage cannot be opted into on a hostname that\n * does not exist yet, so the opt-in list was not merely incomplete, it was\n * uncompletable. `auth.aglyn.com` sat unpinned for a month on exactly that.\n *\n * So the opt-in is ALSO written as a cookie scoped to the workspace domain,\n * and either source turning it on is enough. What the cookie costs is what the\n * paragraph above says it costs: the constant string `internal` now appears in\n * request headers to our own hosts. It carries no identity — it says \"this\n * browser is ours\" and nothing about who is using it — and it rides beside\n * `__session`, which the same domain already carries.\n *\n * ## What still bounds it\n *\n * The cookie is written ONLY where a call site passes `cookieDomain`, and the\n * console's helper passes it only when the current hostname is under that\n * domain. Nothing here writes a cookie on a customer's custom domain, and\n * nothing needs to: published sites are on `aglyn.app` and custom domains,\n * which a `.aglyn.com` cookie cannot reach. That registrable-domain boundary\n * — not per-origin storage — is what keeps an opt-in on our console out of a\n * CUSTOMER's Analytics property while we click through their published site.\n *\n * `INTERNAL_TRAFFIC_GTAG_SNIPPET` is deliberately left on storage alone. It is\n * a constant string inlined into ISR-cached customer HTML (with a verbatim\n * copy in the docs site's config), it cannot be made hostname-aware, and every\n * surface that uses it is a fixed origin that can be pinned directly.\n *\n * ## Bias\n *\n * Opt-in only, never inferred. Wrongly flagging a real customer erases them\n * from every report and a GA4 data filter is not retroactive, so every\n * ambiguous case here resolves to \"not internal\".\n */\nexport const INTERNAL_TRAFFIC_STORAGE_KEY = 'aglyn_traffic_type'\nexport const INTERNAL_TRAFFIC_QUERY_PARAM = 'aglyn_internal'\n\n/**\n * The cookie that carries the same opt-in across every origin under one\n * domain. Same name as the storage key on purpose: one concept, and a browser\n * inspector shows the two halves of it side by side under one label.\n */\nexport const INTERNAL_TRAFFIC_COOKIE_KEY = 'aglyn_traffic_type'\n\n/**\n * 400 days, which is the ceiling Chrome clamps `Max-Age` to anyway. Expiry is\n * not a feature here — the opt-in is meant to be permanent, and a browser that\n * quietly forgets it puts our own browsing back into the launch metrics, which\n * a GA4 data filter cannot undo after the fact.\n */\nconst INTERNAL_TRAFFIC_COOKIE_MAX_AGE = 34_560_000\n\n/**\n * The values of `?aglyn_internal=` that turn the override OFF again. Anything\n * else present turns it on, so `?aglyn_internal` with no value works — that is\n * the form someone types from memory.\n */\nconst OFF_VALUES = new Set(['0', 'false', 'off', 'no'])\n\n/** The browser bits `readInternalTrafficOverride` needs, so a test can supply them. */\nexport interface InternalTrafficOverrideSource {\n  /** `window.location.search`, leading `?` optional. */\n  search?: string | null\n  /** `window.localStorage`, or null where the browser refuses one. */\n  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null\n  /** `document.cookie`, for the READ half. Absent means no cookie source. */\n  cookie?: string | null\n  /**\n   * The domain to scope the cookie WRITE to, bare (`aglyn.com`). Absent means\n   * this call site does not write cookies at all, which is the default and\n   * what every shared caller does — see the module comment. Only a call site\n   * that has already established it is on a first-party host passes it.\n   */\n  cookieDomain?: string | null\n  /** Where a written cookie goes. Defaults to `document.cookie`. */\n  writeCookie?: ((serialized: string) => void) | null\n}\n\n/** Whether a `document.cookie` string carries our opt-in. Never throws. */\nfunction cookieSaysInternal(cookie: string | null | undefined): boolean {\n  if (!cookie) return false\n  for (const part of cookie.split(';')) {\n    const eq = part.indexOf('=')\n    if (eq < 0) continue\n    if (part.slice(0, eq).trim() !== INTERNAL_TRAFFIC_COOKIE_KEY) continue\n    return part.slice(eq + 1).trim() === INTERNAL_TRAFFIC_VALUE\n  }\n  return false\n}\n\n/**\n * Mirror the opt-in into the domain-wide cookie, when the call site asked for\n * it. A no-op everywhere else, which is every shared caller.\n *\n * `SameSite=Lax` and `Secure` because this rides to our own hosts and has no\n * cross-site job; clearing writes the same attributes with `Max-Age=0`,\n * because a cookie is only replaced by one whose domain and path match.\n */\nfunction writeInternalTrafficCookie(\n  source: InternalTrafficOverrideSource,\n  on: boolean,\n): void {\n  const domain = source.cookieDomain\n  if (!domain) return\n  const write =\n    source.writeCookie ??\n    (typeof document === 'undefined'\n      ? null\n      : (serialized: string): void => {\n          document.cookie = serialized\n        })\n  if (!write) return\n  try {\n    write(\n      `${INTERNAL_TRAFFIC_COOKIE_KEY}=${on ? INTERNAL_TRAFFIC_VALUE : ''}` +\n        `; Domain=.${domain}; Path=/; SameSite=Lax; Secure` +\n        `; Max-Age=${on ? INTERNAL_TRAFFIC_COOKIE_MAX_AGE : 0}`,\n    )\n  } catch {\n    // A refused cookie jar leaves `localStorage` holding the opt-in for this\n    // origin, which is where it lived before this existed.\n  }\n}\n\n/**\n * Whether THIS BROWSER has been declared one of ours, applying `?aglyn_internal`\n * first if it is on the URL.\n *\n * Reading and writing in one call is deliberate: the query parameter has to\n * take effect on the pageview that carries it, not on the next one, because\n * the pageview that carries it is already a hit. Persisting it here is what\n * makes the single `?aglyn_internal=1` visit enough.\n *\n * Never throws. A browser with `localStorage` disabled, a sandboxed iframe and\n * a server render all resolve to `false` — the not-internal direction, which\n * is the safe one.\n */\nexport function readInternalTrafficOverride(\n  source?: InternalTrafficOverrideSource,\n): boolean {\n  const resolved: InternalTrafficOverrideSource =\n    source ??\n    (typeof window === 'undefined'\n      ? {}\n      : {\n          search: window.location?.search,\n          storage: safeLocalStorage(),\n          cookie: safeDocumentCookie(),\n        })\n  const storage = resolved.storage\n  // Read the cookie BEFORE the storage gate. A browser that refuses\n  // `localStorage` outright — Safari private mode, a partitioned frame — can\n  // still be one of ours, and before AGL-3175 that browser was unpinnable.\n  let cookieOn = cookieSaysInternal(resolved.cookie)\n  if (!storage) return cookieOn\n  try {\n    const search = resolved.search\n    if (search) {\n      const requested = new URLSearchParams(\n        search.startsWith('?') ? search.slice(1) : search,\n      ).get(INTERNAL_TRAFFIC_QUERY_PARAM)\n      if (requested !== null) {\n        // Both halves move together, so `?aglyn_internal=0` really is an\n        // off switch: clearing storage while the cookie still said `internal`\n        // would leave the browser pinned with nothing local to show for it.\n        if (OFF_VALUES.has(requested.toLowerCase())) {\n          storage.removeItem(INTERNAL_TRAFFIC_STORAGE_KEY)\n          writeInternalTrafficCookie(resolved, false)\n          cookieOn = false\n        } else {\n          storage.setItem(INTERNAL_TRAFFIC_STORAGE_KEY, INTERNAL_TRAFFIC_VALUE)\n          writeInternalTrafficCookie(resolved, true)\n          cookieOn = true\n        }\n      }\n    }\n    return (\n      cookieOn ||\n      storage.getItem(INTERNAL_TRAFFIC_STORAGE_KEY) === INTERNAL_TRAFFIC_VALUE\n    )\n  } catch {\n    // Storage access can throw outright (Safari private mode, a partitioned\n    // third-party context). The cookie is the other half and may still answer.\n    return cookieOn\n  }\n}\n\n/** `document.cookie` where reaching for it does not throw, else null. */\nfunction safeDocumentCookie(): string | null {\n  try {\n    return typeof document === 'undefined' ? null : document.cookie\n  } catch {\n    return null\n  }\n}\n\n/**\n * The override, pinned domain-wide rather than per origin (AGL-3175).\n *\n * For the console, which is the surface served on an open-ended set of\n * `*.aglyn.com` origins. The hostname check is the gate the module comment\n * describes: it is what guarantees no cookie is ever written on a customer's\n * custom domain, and it also keeps `localhost` and preview deployments — where\n * a `Secure` cookie for another domain would be rejected anyway — writing\n * nothing but `localStorage`, exactly as before.\n */\nexport function readInternalTrafficOverrideForDomain(\n  domain: string | null | undefined,\n): boolean {\n  if (typeof window === 'undefined') return false\n  const host = window.location?.hostname ?? ''\n  const underDomain =\n    !!domain && (host === domain || host.endsWith(`.${domain}`))\n  return readInternalTrafficOverride({\n    search: window.location?.search,\n    storage: safeLocalStorage(),\n    cookie: safeDocumentCookie(),\n    cookieDomain: underDomain ? domain : null,\n  })\n}\n\n/** `window.localStorage` where reaching for it does not throw, else null. */\nfunction safeLocalStorage(): Storage | null {\n  try {\n    return window.localStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The same decision as `readInternalTrafficOverride`, as a CONSTANT string of\n * JavaScript, for the surfaces that drive gtag directly (AGL-2064).\n *\n * ## Why a string, and why it must stay constant\n *\n * The tenant runtime serves ISR-cached HTML: one cached document is handed to\n * every visitor, so nothing about this decision may be made while rendering.\n * A server-side branch would bake one browser's answer into the cache for\n * everyone, and a first-client-render branch would break hydration. Emitting\n * the same bytes to everyone and letting them decide AT RUNTIME, in the\n * browser, is the only shape that is both correct and cacheable — the same\n * move `consent.ready` makes one layer up.\n *\n * ## Why it must run before `gtag('config', …)`\n *\n * GA4's internal-traffic filter matches per EVENT, and the events that leak\n * are the ones no call site writes: `session_start`, `first_visit`,\n * `user_engagement` and the automatic `page_view`. A `gtag('set', …)` applies\n * to every hit gtag processes AFTER it in queue order, so placed between the\n * `dataLayer` shim and the `config` call it rides all of them. Placed after\n * `config` it would miss the session's first pageview — which is the whole\n * session, for a marketing visit.\n *\n * ## Safe to inline\n *\n * No interpolation, so nothing can inject; contains no `<` at all, so it\n * cannot close its own `<script>` element. It assumes only that a `gtag`\n * function is already defined, which is the line immediately above it in every\n * call site.\n */\nexport const INTERNAL_TRAFFIC_GTAG_SNIPPET =\n  'try{' +\n  `var aq=new URLSearchParams(location.search).get('${INTERNAL_TRAFFIC_QUERY_PARAM}');` +\n  'if(aq!==null){' +\n  `if(['${[...OFF_VALUES].join(\"','\")}'].indexOf(aq.toLowerCase())>=0)` +\n  `localStorage.removeItem('${INTERNAL_TRAFFIC_STORAGE_KEY}');` +\n  `else localStorage.setItem('${INTERNAL_TRAFFIC_STORAGE_KEY}','${INTERNAL_TRAFFIC_VALUE}');` +\n  '}' +\n  `if(localStorage.getItem('${INTERNAL_TRAFFIC_STORAGE_KEY}')==='${INTERNAL_TRAFFIC_VALUE}')` +\n  `gtag('set',{'${INTERNAL_TRAFFIC_PARAM}':'${INTERNAL_TRAFFIC_VALUE}'});` +\n  '}catch(e){}'\n\n/**\n * The stamp with no opt-in check at all, for a build that has already decided\n * every one of its hits is ours (AGL-2067).\n *\n * Used only where `analyticsEnvironmentForcesInternal()` holds: a\n * non-production build running with the analytics escape hatch on. Nobody\n * reaches that state by accident, so consulting the browser as well would only\n * create a way for it to be wrong.\n */\nexport const INTERNAL_TRAFFIC_FORCED_SNIPPET =\n  `gtag('set',{'${INTERNAL_TRAFFIC_PARAM}':'${INTERNAL_TRAFFIC_VALUE}'});`\n\nexport default readInternalTrafficOverride\n"],"names":["INTERNAL_TRAFFIC_PARAM","INTERNAL_TRAFFIC_VALUE","INTERNAL_TRAFFIC_STORAGE_KEY","INTERNAL_TRAFFIC_QUERY_PARAM","INTERNAL_TRAFFIC_COOKIE_KEY","INTERNAL_TRAFFIC_COOKIE_MAX_AGE","OFF_VALUES","Set","cookieSaysInternal","cookie","part","split","eq","indexOf","slice","trim","writeInternalTrafficCookie","source","on","domain","cookieDomain","write","writeCookie","document","serialized","readInternalTrafficOverride","window","resolved","search","location","storage","safeLocalStorage","safeDocumentCookie","cookieOn","requested","URLSearchParams","startsWith","get","has","toLowerCase","removeItem","setItem","getItem","readInternalTrafficOverrideForDomain","host","hostname","underDomain","endsWith","localStorage","INTERNAL_TRAFFIC_GTAG_SNIPPET","join","INTERNAL_TRAFFIC_FORCED_SNIPPET"],"mappings":"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"}

package/src/lib/app-utils/lineal-order.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { LinealDirectiveFlag } from '../foundation/definitions/components.types';
+import type { ComponentId, ComponentsLinealOrder, PluginId } from '../foundation/definitions/components.types';
+/** A directive as a schema declares it, or as the generated palette carries it. */
+/**
+ * A lineal order as a JSON emitter writes it (AGL-2905): the directive as
+ * the enum's string value rather than the enum, so a generated catalog can
+ * carry it and a validator can read it back without the enum in scope.
+ */
+export type JsonLinealOrder = [
+    directiveType: `${LinealDirectiveFlag}`,
+    directiveDefinition: string[] | {
+        plugins?: string[];
+        components?: string[];
+    }
+];
+export type LinealOrderLike = ComponentsLinealOrder | JsonLinealOrder;
+/**
+ * Which half of a lineal directive a candidate fails, or `null` when the
+ * directive admits it.
+ *
+ * `restrictChildren` and `restrictParent` are one grammar — a `limitedTo` or
+ * `forbid` flag over a component list, a plugin list, or both — read from two
+ * sides: the besigner's drop check asks it about a dragged element, and the
+ * AI node-tree validator asks it about a node a model emitted. The answer has
+ * to be the same answer, so the rule lives here with no editor attached and
+ * both callers read it (AGL-2905).
+ *
+ * A `limitedTo` list that is present but empty admits nothing — that is how a
+ * component declares it takes no children at all (`layoutSlot`), and the
+ * child-contract audit reads the same shape the same way.
+ */
+export declare function checkLinealOrder(componentId: ComponentId | undefined, pluginId: PluginId | undefined, order: LinealOrderLike): 'component' | 'plugin' | null;
+/**
+ * Whether `child` may sit directly under `parent`, reading the child's
+ * `restrictParent` and the parent's `restrictChildren` — the two directives
+ * the besigner's drop check consults, in that order.
+ */
+export declare function linealRelationshipPermits(child: {
+    componentId?: ComponentId;
+    pluginId?: PluginId;
+    restrictParent?: LinealOrderLike;
+}, parent: {
+    componentId?: ComponentId;
+    pluginId?: PluginId;
+    restrictChildren?: LinealOrderLike;
+}): boolean;

package/src/lib/app-utils/lineal-order.js

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { LinealDirectiveFlag } from "../foundation/definitions/components.types.js";
+/**
+ * Which half of a lineal directive a candidate fails, or `null` when the
+ * directive admits it.
+ *
+ * `restrictChildren` and `restrictParent` are one grammar — a `limitedTo` or
+ * `forbid` flag over a component list, a plugin list, or both — read from two
+ * sides: the besigner's drop check asks it about a dragged element, and the
+ * AI node-tree validator asks it about a node a model emitted. The answer has
+ * to be the same answer, so the rule lives here with no editor attached and
+ * both callers read it (AGL-2905).
+ *
+ * A `limitedTo` list that is present but empty admits nothing — that is how a
+ * component declares it takes no children at all (`layoutSlot`), and the
+ * child-contract audit reads the same shape the same way.
+ */ export function checkLinealOrder(componentId, pluginId, order) {
+    const [directiveType, directiveDefinition] = order;
+    const flag = directiveType;
+    const components = Array.isArray(directiveDefinition) ? directiveDefinition : directiveDefinition == null ? void 0 : directiveDefinition.components;
+    const plugins = Array.isArray(directiveDefinition) ? undefined : directiveDefinition == null ? void 0 : directiveDefinition.plugins;
+    if (flag === LinealDirectiveFlag.DISALLOW) {
+        if (components == null ? void 0 : components.some((id)=>id === componentId)) return 'component';
+        if (plugins == null ? void 0 : plugins.some((id)=>id === pluginId)) return 'plugin';
+        return null;
+    }
+    if (flag === LinealDirectiveFlag.LIMIT_TO) {
+        if (Array.isArray(components) && (components.length === 0 || !components.some((id)=>id === componentId))) {
+            return 'component';
+        }
+        if (Array.isArray(plugins) && (plugins.length === 0 || !plugins.some((id)=>id === pluginId))) {
+            return 'plugin';
+        }
+    }
+    return null;
+}
+/**
+ * Whether `child` may sit directly under `parent`, reading the child's
+ * `restrictParent` and the parent's `restrictChildren` — the two directives
+ * the besigner's drop check consults, in that order.
+ */ export function linealRelationshipPermits(child, parent) {
+    if (child.restrictParent && checkLinealOrder(parent.componentId, parent.pluginId, child.restrictParent)) {
+        return false;
+    }
+    if (parent.restrictChildren && checkLinealOrder(child.componentId, child.pluginId, parent.restrictChildren)) {
+        return false;
+    }
+    return true;
+}
+
+//# sourceMappingURL=lineal-order.js.map