@jskit-ai/connectors-catalog 0.1.1

package/patterns/oauth-connection/example/integrations.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "wordpress": {
+      "source": "own",
+      "clientId": "YOUR_ASSIGNED_CLIENT_ID",
+      "clientSecretRef": "env:WORDPRESS_COM_CLIENT_SECRET",
+      "callbackUrlRef": "env:WORDPRESS_COM_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "publishing": {
+      "provider": "wordpress-com",
+      "displayName": "Publishing account",
+      "accountMode": "per-user",
+      "scopes": ["users", "sites", "posts"],
+      "authentication": { "method": "oauth2", "registrationRef": "wordpress" }
+    }
+  }
+}

package/patterns/paddle-catalogue/PATTERN.md

@@ -0,0 +1,78 @@
+---
+id: connectors/paddle-catalogue
+title: Create Paddle products with prices
+summary: Compose a sequential catalogue batch and preserve partial success for application-owned recovery.
+keywords: paddle, products, prices, batch, payments
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Create Paddle products with prices
+
+## Use when
+
+Use the [Paddle setup guide](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/paddle.md) to configure and verify the
+application's merchant key. This recipe creates catalogue entries only.
+Checkout, subscriptions and charging customers are separate application work.
+
+## Do not use when
+
+Use the payments-core reviewed catalogue workflow when the application requires
+durable publication recovery. This bounded recipe is not that workflow.
+
+## Framework APIs
+
+Adapt [create-products.js](example/create-products.js) into the application's
+backend. Replace its repository-relative provider import with
+`@jskit-ai/connectors-catalog/server/paddle`. Pass the application's connection
+runtime, authenticated context, integration ID and an array of `{ product,
+price }` inputs described in the guide. The newly created product supplies the
+price's product_id. One item implements product-with-price; several implement
+batch creation. The limit of 100 items is this recipe's bounded workload choice,
+not a Paddle API limit. It executes serially and does not invent a remote batch
+API or transaction.
+
+## Invariants
+
+The recipe validates the entire cloned batch before the first write. It calls
+the ordinary runtime for each request, preserving authorization and the
+connection's configured sandbox/live environment. The sandbox setting used for
+local schema validation sends no request and does not override runtime routing.
+
+## Product decisions
+
+For assistant use, authorize the complete cloned request with
+`authorizeAssistantAction`, action `products.create` for one item or
+`products.batchCreate` for several, before calling the recipe. The host must
+bind approval to that exact snapshot and caller. Individual runtime invocations
+still enforce their policies; do not turn off runtime authorization to bypass
+an additional required approval. Application use instead enforces its normal
+administrator permissions. This file does not supply a public HTTP endpoint.
+
+## Avoid
+
+Retain `completed` and `failed` in app-owned operation state. A failed price
+step includes the newly created product ID. No later items run after failure,
+and no failed call is retried. An interrupted request may have succeeded at
+Paddle; inspect the merchant catalogue before repeating any write. Process
+termination can prevent the returned report from being saved, so an application
+needing crash recovery must record each completed step durably. This small
+recipe does not promise crash recovery, rollback or exactly-once execution.
+
+## Variation points
+
+CLI users can call this same JavaScript recipe with their own runtime. Vibe64
+configures the project; it does not execute catalogue writes on configuration
+save. Laravel applications implement this composition with their own framework
+and Paddle client, without importing JavaScript or depending on Vibe64.
+
+## Example files
+
+- [create-products.js](example/create-products.js): sequential product/price
+  composition with input validation and a partial-success report.
+
+## Verification
+
+Exercise the recipe with controlled provider responses. Verify whole-batch
+validation before writes, authorization for each operation, product-to-price
+identity, stop-on-failure behavior and preservation of completed IDs. A returned
+report does not prove durable recovery or live merchant acceptance.

package/patterns/paddle-catalogue/example/create-products.js

@@ -0,0 +1,38 @@
+import { paddleProvider } from "../../../src/server/paddle.js";
+
+// Application-owned composition: pass an application-mode connection runtime.
+// An assistant host must approve the complete batch before calling this recipe.
+async function createProductsWithPrices({ runtime, context, integrationId, items, signal }) {
+  if (!Array.isArray(items) || !items.length || items.length > 100) {
+    throw new TypeError("Supply between 1 and 100 products with prices.");
+  }
+  const batch = structuredClone(items);
+  // Validate every item before the first write, using the adapter's own schema.
+  for (const item of batch) {
+    if (!item || typeof item !== "object" || Object.keys(item).some((key) => !["product", "price"].includes(key)) ||
+        !item.product || !item.price || Object.hasOwn(item.price, "product_id")) {
+      throw new TypeError("Each item needs product and price inputs; the new product supplies product_id.");
+    }
+    paddleProvider.operations["products.create"].request(item.product, { environment: "sandbox" });
+    paddleProvider.operations["prices.create"].request({ ...item.price, product_id: `pro_${"a".repeat(26)}` }, { environment: "sandbox" });
+  }
+  const completed = [];
+  for (const [index, item] of batch.entries()) {
+    let productId;
+    let stage = "product";
+    try {
+      const product = await runtime.invoke({ context, integrationId, signal, operation: "products.create", input: item.product });
+      productId = product.data.id;
+      stage = "price";
+      const price = await runtime.invoke({ context, integrationId, signal, operation: "prices.create", input: { ...item.price, product_id: productId } });
+      completed.push({ index, productId, priceId: price.data.id });
+    } catch {
+      // Do not replay the batch: a failed request may have reached Paddle.
+      // Do not include raw provider errors or credential-bearing diagnostics.
+      return { completed, failed: { index, stage, ...(productId ? { productId } : {}), outcome: "requires-review" } };
+    }
+  }
+  return { completed, failed: null };
+}
+
+export { createProductsWithPrices };

package/patterns/public-image/PATTERN.md

@@ -0,0 +1,84 @@
+---
+id: connectors/public-image
+title: Public logo images from portable integration configuration
+summary: Resolve a publishable image key deliberately and use the shared URL library in a browser, backend or CLI.
+keywords: connectors, integrations, logo-dev, images, public-key, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Public logo images from portable integration configuration
+
+## Use when
+
+Use for Logo.dev's public image service. `createLogoDevImageUrl` is implemented
+in the library; the example owns only application configuration and wiring.
+This path does not need a server connection grant or a database.
+
+## Do not use when
+
+Private JSON API keys, user OAuth tokens and managed service credentials must
+not be placed in public image URLs. Logo.dev search/describe use different
+credentials and are outside this pattern.
+
+## Product decisions
+
+Choose the domains that may load images, attribution placement and missing-image
+behavior. Choose whether a build step publishes the permitted key in public
+configuration or an authorized backend returns image URLs. The application's
+existing access policy applies before exposing its configured resources.
+
+## Invariants
+
+- CLI and Vibe64 edit the same reference-only `integrations.json`.
+- Only a `pk_` key enters an image URL; a private key fails validation.
+- URL creation is local and does not establish a verified account connection.
+- Browser load/error events report delivery. A monogram is not proof of a brand logo.
+- Domain restrictions concern the app that loads the image, including previews
+  and custom domains. The editor VM may have a different origin.
+
+## Framework APIs
+
+Use `parseIntegrationConfiguration` from connectors-core/shared/configuration,
+`logoDevDefinition` from connectors-catalog/shared, and
+`createLogoDevImageUrl` from connectors-catalog/client/logo-dev. The latter is
+portable to Node and browsers and exposes `logoDevImageSchema` for input fields.
+Use the application's reference resolver; no environment object goes to the
+browser. See [provider setup](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/logo-dev.md) for inputs and limitations.
+
+## Example files
+
+`integrations.json` is ordinary application source. `logo-url.js` demonstrates
+resolving its chosen integration and producing a public URL from the library.
+Supply authorized configuration, a resolver and the desired image input:
+
+```js
+const url = await logoUrlFromConfiguration({
+  configurationText, integrationId: "logos", resolveReference,
+  image: { domain: "example.com", fallback: "404" }
+});
+```
+
+In Vue, compute the URL from approved public configuration and bind `:src` on
+an `<img>` with `alt`, `referrerpolicy="origin"` and an `@error` fallback. A CLI
+can print or embed the same URL without generating an application. Treat the
+returned URL as containing a public key; do not substitute a private credential.
+
+## Variation points
+
+Application code owns public configuration delivery, allowed domains, display
+size, theme and fallback. Use explicit permanent-hosting arrangements if the
+product needs to retain or redistribute provider assets.
+
+## Verification
+
+Library tests cover key and domain validation, option bounds and fixed-origin
+URL construction. Browser fixtures exercise simulated image success and error.
+Source-pattern tests use a supplied resolver and reject a different provider
+slot. Editor tests verify reference-only source, field errors and reload.
+These checks need neither live credentials nor generated sample applications.
+
+## Avoid
+
+Do not call server `connectApiKey` to manufacture a Connected receipt for this
+image flow. Do not send a secret key, an environment dump or a caller-selected
+service origin to the browser. Do not treat key naming as provider quota isolation.

package/patterns/public-image/example/integrations.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "logos": {
+      "provider": "logo-dev",
+      "displayName": "Company logos",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:LOGO_DEV_PUBLISHABLE_KEY" }
+    }
+  }
+}

package/patterns/public-image/example/logo-url.js

@@ -0,0 +1,16 @@
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { logoDevDefinition } from "@jskit-ai/connectors-catalog/shared";
+import { createLogoDevImageUrl } from "@jskit-ai/connectors-catalog/client/logo-dev";
+
+// The application authorizes access before passing its configuration and resolver.
+async function logoUrlFromConfiguration({ configurationText, integrationId, resolveReference, image }) {
+  const configuration = parseIntegrationConfiguration(configurationText, { providers: [logoDevDefinition], allowUnknownProviders: true });
+  const integration = configuration.integrations[integrationId];
+  if (!Object.hasOwn(configuration.integrations, integrationId) || integration.provider !== "logo-dev") {
+    throw new Error("Select a configured Logo.dev integration.");
+  }
+  const publishableKey = await resolveReference(integration.authentication.secretRef);
+  return createLogoDevImageUrl({ ...image, publishableKey });
+}
+
+export { logoUrlFromConfiguration };

package/patterns/redshift-queries/PATTERN.md

@@ -0,0 +1,150 @@
+---
+id: connectors/redshift-queries
+title: Redshift queries with shared AWS credentials
+summary: Compose file configuration, Redshift Data API operations and application query ownership.
+keywords: redshift, aws, sql, warehouse, serverless, provisioned, iam, connectors, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Redshift queries with shared AWS credentials
+
+## Use when
+
+A CLI operator or application backend needs database/schema/table metadata or authorized SQL in
+one configured Redshift warehouse. JSKIT owns configuration validation, AWS SDK
+signing, operation input validation, target checks and response parsing. The
+application owns which user may submit a query or access its result.
+
+## Do not use when
+
+This fragment does not provide application login, per-user IAM Identity Center
+federation, warehouse provisioning or a managed paid/public allocation. Never
+turn a shared AWS key into an unrestricted SQL endpoint for application users.
+SQL can modify data; read-only behavior requires appropriate database grants.
+
+## Product decisions
+
+Select serverless or provisioned in the same JSON edited by Vibe64. Serverless
+requires a workgroup name; provisioned requires a cluster identifier and may use
+an explicit database user. Both require a database and region. Store AWS secrets
+outside the file. Temporary credentials additionally need `sessionTokenRef` and
+host renewal. See the [Redshift guide](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/amazon-redshift.md) for setup,
+field names, automation feasibility and remaining federation work.
+
+## Invariants
+
+Use the application's existing authentication and authorization policy to build
+the trusted context. Bind logical query tokens and returned statement IDs to
+the actual application/user in application-owned state; a text file can hold
+that state. Authorize exact SQL, parameter values and statement ownership before
+invoking the service. Matching the configured warehouse is only a target check.
+
+The library does not resolve ambient AWS profiles or switch to a more privileged
+account after a denial. The application resolves its own credential bindings; editable references do
+not grant AWS permissions. This shared credential mode has no provider callback
+URL and does not depend on an Online registration or allocation.
+
+## Framework APIs
+
+Follow the [API-key connection pattern](../api-key-connection/PATTERN.md) to read
+configuration, create protected file connection storage, resolve explicit
+bindings and implement `authorize`. Register this runtime export:
+
+```js
+import { amazonRedshiftProvider } from "@jskit-ai/connectors-catalog/server/amazon-redshift";
+const providers = [amazonRedshiftProvider];
+// Pass providers with configuration, store, resolveReference and authorize
+// to createConnectionService or the ordinary connector Feature.
+```
+
+The library's `connectApiKey({context, integrationId})` reads a table metadata
+page. It does not submit SQL or grant future query permission. Use
+`databases.list` for visible database names, `schemas.list` for schemas in the
+configured database, `tables.list` for tables and `table.describe` for columns.
+Each listing accepts `maxResults` (1–1000) and an opaque `nextToken`; schema
+listing also accepts `schemaPattern`. An absent or empty NextToken ends paging.
+Database names returned by discovery do not change this connection's configured
+target or authorize another database. Use another project-owned configuration
+slot for another database and authorize metadata visibility before invocation.
+
+## Example files
+
+[example/integrations.json](example/integrations.json) has two independent
+configuration slots demonstrating both deployment types. Actual resource names
+and environment bindings must come from the owner. Do not generate a new app to
+use these libraries; compose them in the existing backend or CLI entry point.
+
+After the application has authorized the statement and stored its logical
+request token, call:
+
+```js
+const submitted = await service.invoke({
+  context, integrationId: "serverless-reports", operation: "query.start",
+  input: {
+    sql: "select order_id::varchar, total from reporting.orders where customer_id = :customer limit 100",
+    parameters: [{ name: "customer", value: authorizedCustomerId }],
+    clientToken: storedLogicalRequestToken
+  }
+});
+// Persist submitted.Id with the authorized application's query owner.
+const status = await service.invoke({
+  context, integrationId: "serverless-reports", operation: "query.status",
+  input: { statementId: submitted.Id }
+});
+```
+
+Use parameters for values; do not concatenate user input into the SQL. Tokens
+are required, case-sensitive and 1–64 characters. Reuse the same token only for
+the same logical request and identical input within AWS's deduplication window.
+An ambiguous response must not trigger an automatic submission with a new token.
+
+A returned ID is submission, not completion. `query.status` reports SUBMITTED,
+PICKED, STARTED, FINISHED, ABORTED or FAILED. The application controls bounded
+polling and cancellation. When status is FINISHED with a result set:
+
+```js
+const page = await service.invoke({
+  context, integrationId: "serverless-reports", operation: "query.results",
+  input: { statementId: authorizedStatementId }
+});
+// ColumnMetadata describes each position in Records. Preserve typed cells.
+// If another page is needed, pass page.NextToken unchanged as nextToken.
+```
+
+Result cells retain AWS's tags: `stringValue`, `longValue`, `doubleValue`,
+`booleanValue`, `isNull` and `blobValue`. Do not collapse empty strings, zero or
+false into null. Binary values are Uint8Array; explicitly encode them in an
+application JSON response. Large integers outside JavaScript's safe range are
+rejected: select them as VARCHAR for exact text. Results are one AWS page;
+there is no `maxResults` parameter for `query.results`.
+
+For explicit remote cancellation, authorize the statement owner then invoke
+`query.cancel` with its ID. The returned boolean receipt does not establish
+rollback or a final job state. Read status if the final outcome is needed.
+Closing a UI, aborting local HTTP or disconnecting does not cancel remote SQL.
+
+## Variation points
+
+Change only the configured resource slot when targeting a provisioned cluster.
+The operation interface stays the same. An explicit `databaseUser` uses that
+database identity; omit it for the IAM-derived identity. Table listing and
+description accept a bounded page size and opaque cursors. Metadata filters
+support AWS's SQL-style patterns.
+
+## Avoid
+
+Do not expose arbitrary database/workgroup overrides, use query IDs as bearer
+authorization, log SQL/result metadata indiscriminately, assume that a table
+listing proves every SELECT permission, or reimplement AWS signing in scaffolding.
+The runtime does not enforce SELECT-only SQL by parsing or matching prefixes.
+
+## Verification
+
+Run the single focused `test/amazon-redshift.test.js` file in the catalogue
+package. It uses real SDK signing with controlled responses and file storage.
+It covers both targets, input validation, SQL parameters, statement checks,
+typed result pages, credentials, errors and local cancellation. Shared-form
+browser checks pass at phone, tablet and desktop sizes; Public editor checks
+pass at phone/desktop sizes for both deployment types, region selection,
+validation, inactive-field removal and save/reload.
+No live AWS account, executed SQL or generated application is claimed.

package/patterns/redshift-queries/example/integrations.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "serverless-reports": {
+      "provider": "amazon-redshift",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:REPORTING_AWS_SECRET_ACCESS_KEY" },
+      "settings": {
+        "deploymentType": "serverless",
+        "region": "us-east-1",
+        "accessKeyIdRef": "env:REPORTING_AWS_ACCESS_KEY_ID",
+        "workgroup": "analytics",
+        "database": "dev"
+      }
+    },
+    "cluster-reports": {
+      "provider": "amazon-redshift",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:CLUSTER_AWS_SECRET_ACCESS_KEY" },
+      "settings": {
+        "deploymentType": "provisioned",
+        "region": "us-east-1",
+        "accessKeyIdRef": "env:CLUSTER_AWS_ACCESS_KEY_ID",
+        "clusterIdentifier": "analytics-cluster",
+        "database": "dev",
+        "databaseUser": "report_reader"
+      }
+    }
+  }
+}

package/patterns/source-scanning/PATTERN.md

@@ -0,0 +1,83 @@
+---
+id: connectors/source-scanning
+title: Authorised project source scans with Wiz
+summary: Use the shared scanner runtime from a CLI or a host worker with portable configuration and explicit source ownership.
+keywords: connectors, integrations, wiz, security, source, scanning, cli, worker, cancellation
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Authorised project source scans with Wiz
+
+## Use when
+
+A CLI or host needs to scan an authorised source snapshot with its own Wiz account.
+`createWizScanner` implements configuration checks, command construction,
+credential isolation, bounded process execution, report validation and cleanup.
+The example wires that library to application-owned authority and snapshot lookup.
+
+## Do not use when
+
+This is not an HTTP application-data connector, user login, a managed gateway,
+or an implementation of Vibe64's coding agents. It does not generate an app.
+Auth0 and native Windows execution are not implemented in the current runner.
+
+## Product decisions
+
+The host chooses which principals may scan which projects, the stable application
+and shared subject identities, snapshot lifetime, worker resource/network limits,
+Wiz policies and authorised report readers. It decides how to display findings
+and whether a blocking verdict prevents a later operation.
+
+## Invariants
+
+- CLI and UI edit the same reference-only `integrations.json`.
+- Browser input never supplies a source path, executable, environment or identity.
+- The host checks access before resolving source and credentials.
+- The snapshot must remain immutable while the scan runs; keep its revision with
+  the findings and mark the result stale when current source differs.
+- A passed policy verdict is not a proof that there are no vulnerabilities.
+- Missing/invalid reports, cancellation and failed scans never become clean scans.
+- Provider credentials are isolated from coding-agent sessions and credentials.
+- The host supplies its own authorized provider credentials; editor edition does
+  not select a shared Vibe64 provider account.
+
+## Framework APIs
+
+Use `parseIntegrationConfiguration` from connectors-core/shared/configuration,
+`wizDefinition` from connectors-catalog/shared, and `createWizScanner` from
+connectors-catalog/server/wiz. Supply the host's `authorize`, `resolveReference`,
+`resolveScanTarget` and installed CLI absolute path. The runtime's `scan` operation
+accepts only context, integration ID and an optional AbortSignal.
+See [Wiz setup and limits](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/wiz.md).
+
+## Example files
+
+`source-scanner.js` reads a normal text configuration file and returns the scanner.
+Both an authenticated HTTP handler and an ordinary CLI command can call it.
+Its callbacks belong to the application; do not replace them with unconditional
+approval in a multi-user service. Do not run this example merely to validate source.
+
+## Variation points
+
+CLI commands can use local user authority; a server uses its workspace/project
+policy. Hosts may set the deadline, report-size limit, proxy and CA environment
+for an isolated worker. Snapshot creation and findings storage stay host-owned.
+
+A Laravel application can use a PHP worker to invoke the same installed Wiz CLI
+or call an explicitly configured scan worker over HTTP. It reads ordinary JSON
+and needs no Node/JSKIT runtime. That PHP or HTTP implementation owns its process
+and identity boundary; this package supplies a working JavaScript implementation
+and documents the protocol, not an already implemented PHP library or gateway.
+
+## Verification
+
+Use a controlled executable and temporary source to verify command arguments,
+isolated credentials, policy results, malformed reports, cancellation and cleanup.
+Editor checks cover all configuration fields and persistence. Actual authentication
+and findings require separately authorised provider acceptance.
+
+## Avoid
+
+Do not infer workspace grants from a shared slot, return raw provider stderr,
+replay scans automatically, pass arbitrary CLI flags, use a mutable working tree
+as if it were a fixed revision, or substitute a generic API reader for source scans.

package/patterns/source-scanning/example/source-scanner.js

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { wizDefinition } from "@jskit-ai/connectors-catalog/shared";
+import { createWizScanner } from "@jskit-ai/connectors-catalog/server/wiz";
+
+export async function projectSourceScanner({ configFile = "integrations.json", installedWizCliPath,
+  authorize, resolveReference, resolveScanTarget, environment }) {
+  const configuration = parseIntegrationConfiguration(await readFile(configFile, "utf8"), {
+    providers: [wizDefinition], allowUnknownProviders: true
+  });
+  return createWizScanner({ configuration, executable: installedWizCliPath,
+    authorize, resolveReference, resolveScanTarget, environment });
+}

package/src/client/firebase-cloud-messaging.js

@@ -0,0 +1,10 @@
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { firebaseCloudMessagingDefinition } from "../shared/firebase-cloud-messaging.js";
+
+function firebaseCloudMessagingWebConfiguration(settings) {
+  if (settings?.clientMode !== "web") throw new TypeError("Select Include web push before configuring browser registration.");
+  const values = validateSchemaPayload({ schema: firebaseCloudMessagingDefinition.settingsSchema(settings), mode: "replace" }, settings);
+  return { firebaseConfig: { projectId: values.projectId, apiKey: values.apiKey, appId: values.appId, messagingSenderId: values.appId.split(":")[1] }, vapidKey: values.vapidKey };
+}
+
+export { firebaseCloudMessagingWebConfiguration };

package/src/client/google-analytics.js

@@ -0,0 +1,72 @@
+// Optional browser implementation. The application owns consent and route hooks.
+const installations = new WeakMap();
+
+function createGoogleAnalytics({ measurementId, window: browser = globalThis.window } = {}) {
+  if (typeof measurementId !== "string" || !/^G-[A-Z0-9]+$/.test(measurementId) || measurementId.length > 64) throw new TypeError("Supply a valid GA4 Measurement ID.");
+  if (!browser?.document) throw new TypeError("Initialize Google Analytics in the browser after hydration.");
+  const existing = installations.get(browser);
+  if (existing) {
+    if (existing.measurementId !== measurementId) throw new Error("This page already has an Analytics owner. Reload to change the Measurement ID.");
+    return existing.controller;
+  }
+  if (browser.gtag || browser.document.querySelector('script[src*="googletagmanager.com/"]')) throw new Error("Use the application's existing Google tag or Tag Manager instead of installing a second tracker.");
+  if (browser.dataLayer !== undefined && !Array.isArray(browser.dataLayer)) throw new TypeError("The existing dataLayer must be an array.");
+  let enabled = false, initialized = false, disposed = false, script, lastPage;
+  const disabledKey = `ga-disable-${measurementId}`;
+  browser[disabledKey] = true;
+  function active() { if (disposed) throw new Error("Analytics has been disposed. Reload before configuring tracking again."); }
+  function queue(...args) { browser.gtag(...args); }
+  const controller = Object.freeze({
+    setConsent(granted) {
+      active();
+      if (typeof granted !== "boolean") throw new TypeError("Pass an explicit consent boolean.");
+      enabled = granted;
+      browser[disabledKey] = !granted;
+      if (!granted) { lastPage = undefined; return; }
+      if (initialized) return;
+      // Check again: another integration may have installed a tag since creation.
+      if (browser.gtag || browser.document.querySelector('script[src*="googletagmanager.com/"]')) {
+        enabled = false; browser[disabledKey] = true;
+        throw new Error("Use the application's existing Google tracking installation.");
+      }
+      browser.dataLayer ||= [];
+      browser.gtag = function () { browser.dataLayer.push(arguments); };
+      queue("js", new Date());
+      queue("config", measurementId, { send_page_view: false });
+      script = browser.document.createElement("script");
+      script.async = true;
+      script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}`;
+      browser.document.head.appendChild(script);
+      initialized = true;
+    },
+    pageView({ location = browser.location.href, title = browser.document.title } = {}) {
+      active();
+      if (!enabled) return false;
+      const url = new URL(location);
+      if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) throw new TypeError("Supply a public HTTP(S) page URL without credentials.");
+      if (typeof title !== "string") throw new TypeError("Supply a page title.");
+      if (lastPage === url.href) return false;
+      const previous = lastPage;
+      lastPage = url.href;
+      queue("event", "page_view", { send_to: measurementId, page_location: url.href, page_title: title, ...(previous ? { page_referrer: previous } : {}) });
+      return true;
+    },
+    event(name, parameters = {}) {
+      active();
+      if (!enabled) return false;
+      if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,39}$/.test(name) || /^(?:google_|ga_|firebase_)/.test(name) || name === "page_view") throw new TypeError("Use a valid event name; page views use pageView.");
+      if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) throw new TypeError("Supply an event parameter object.");
+      queue("event", name, { ...parameters, send_to: measurementId });
+      return true;
+    },
+    dispose() {
+      enabled = false; disposed = true; browser[disabledKey] = true;
+      script?.remove();
+      // Loaded Google code cannot be unloaded. Keep ownership until page reload.
+    }
+  });
+  installations.set(browser, { measurementId, controller });
+  return controller;
+}
+
+export { createGoogleAnalytics };