@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/marketplace-provenance.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @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.
+ */
+/**
+ * Everything an org can publish to the marketplace (AGL-654).
+ *
+ * The union lives in core rather than the marketplace plugin because the
+ * console reasons about installed artifacts too — a Plugins index that cannot
+ * name an artifact type cannot render an update chip — and module boundaries
+ * (rightly) forbid an app depending on an addon lib. The marketplace model
+ * re-exports it, so publishing code still reads it from one place.
+ */
+export type MarketplaceArtifactType = 'component' | 'template' | 'plugin' | 'layout' | 'datasetSchema' | 'emailTemplate'
+/**
+ * A campaign email design, installed as a new `kind: 'email'` screen.
+ *
+ * Distinct from `emailTemplate`, which is a design FOR one entry in the
+ * fixed transactional catalog and can only ever land on that same key. A
+ * starter belongs to no key: it is a blank-page replacement for the composer,
+ * so it installs as a new document and the tenant may install ten of them.
+ * Folding the two together would give one install button two behaviors and
+ * would make the catalog key an absent-field discriminator.
+ */
+ | 'emailStarter' | 'theme';
+/**
+ * Install provenance (AGL-1015): where an installed artifact came from, at
+ * what version, and what it looked like when it arrived.
+ *
+ * Every install route used to stamp its own shape — plugins wrote a pin,
+ * dataset schemas a `source`, email templates an `installedFrom`, components a
+ * `marketplace` — and none of them kept the content as installed. Without the
+ * original there is no way to tell the publisher's change from the user's, so
+ * an update can only overwrite. This module defines the one shape all install
+ * routes write and the one reader everything else asks.
+ */
+/**
+ * Immutable, content-addressed base snapshots — the content exactly as
+ * installed, keyed by its own hash and stored outside the user's edit path.
+ *
+ * Top-level rather than per-host on purpose: the same listing version installed
+ * onto twenty sites is one document, and re-installing it rewrites nothing.
+ */
+export declare const ARTIFACT_BASE_COLLECTION = "marketplaceArtifactBases";
+/**
+ * Firestore's per-document ceiling is 1 MiB. Snapshots are stored whole, so
+ * anything near it is refused rather than truncated — a partial base is worse
+ * than no base, because a diff would report the missing half as user edits.
+ */
+export declare const ARTIFACT_BASE_MAX_BYTES: number;
+/** The provenance stamp written on every installed artifact (AGL-1015). */
+export interface InstalledFrom {
+    listingId: string;
+    /** The listing version installed, as a string; null when unversioned. */
+    version: string | null;
+    /** Content hash of the base snapshot — the key into {@link ARTIFACT_BASE_COLLECTION}. */
+    sha256: string | null;
+    artifactType: MarketplaceArtifactType;
+    installedAt: unknown;
+    /** The publishing org (`listing.profileId`, org-owned since AGL-652). */
+    publisherOrgId: string | null;
+    /**
+     * What review said about THE VERSION INSTALLED, recorded at install time.
+     *
+     * Optional because six of the seven artifact types are auto-listed and have
+     * no verdict to record. Where it is written it is a fact about one version
+     * and is never recomputed from the listing afterwards: a listing that earns
+     * `reviewStatus: 'verified'` next month did not retroactively review the
+     * bytes installed today, and a surface that resolved assurance live would
+     * say it did. Stamping it is what keeps "unreviewed" from decaying into a
+     * silence a reader mistakes for approval.
+     */
+    assurance?: 'approved' | 'unreviewed' | 'rejected';
+}
+/**
+ * How much is actually known about where an artifact came from.
+ *
+ * `inferred` exists because the marketplace shipped before this stamp did:
+ * pre-AGL-1015 installs carry a listing id somewhere but no hash and no base.
+ * Calling those `recorded` would let an update think it has an origin to merge
+ * against; calling them `unknown` would throw away a listing id we really do
+ * have. They are their own state, and the UI says "installed before update
+ * tracking" rather than implying either.
+ */
+export type ProvenanceState = 'recorded' | 'inferred' | 'unknown';
+export interface ResolvedProvenance {
+    state: ProvenanceState;
+    listingId: string | null;
+    version: string | null;
+    sha256: string | null;
+    artifactType: MarketplaceArtifactType | null;
+    publisherOrgId: string | null;
+    /**
+     * A base snapshot exists, so this artifact can be diffed and safely updated.
+     * False for everything installed before the stamp — and saying so plainly is
+     * the point: a merge built on a fabricated origin destroys work silently.
+     */
+    updatable: boolean;
+}
+/**
+ * Reads provenance off an installed document, tolerating every shape the
+ * install routes wrote before AGL-1015.
+ *
+ * The legacy fields are read rather than migrated: a batch backfill could only
+ * ever recover the listing id and version, which is exactly what this recovers
+ * lazily, and it cannot invent a base snapshot. Installs re-stamp themselves
+ * properly the next time they are updated.
+ */
+export declare function resolveProvenance(doc: {
+    installedFrom?: Partial<InstalledFrom> | null;
+    /** Component installs (`hosts/{h}/components`). */
+    marketplace?: {
+        listingId?: string;
+        profileId?: string;
+        version?: unknown;
+    } | null;
+    /** Template, layout and dataset-schema installs. */
+    source?: {
+        type?: string;
+        listingId?: string;
+        version?: unknown;
+    } | null;
+    /** Plugin pins are their own provenance: the pin IS the version. */
+    pluginId?: string;
+    listingId?: string;
+    profileId?: string;
+    version?: unknown;
+    sha256?: string;
+} | null | undefined, fallbackArtifactType?: MarketplaceArtifactType): ResolvedProvenance;
+/**
+ * Deterministic JSON with object keys in sorted order, so the same content
+ * hashes to the same id no matter what order Firestore handed the fields back.
+ *
+ * `undefined` members are dropped exactly as `JSON.stringify` drops them, which
+ * keeps `{a: 1}` and `{a: 1, b: undefined}` — the same document after a
+ * Firestore round-trip — hashing alike.
+ */
+export declare function stableStringify(value: unknown): string;

package/src/lib/app-utils/marketplace-provenance.js

@@ -0,0 +1,136 @@
+/**
+ * @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.
+ */ /**
+ * Everything an org can publish to the marketplace (AGL-654).
+ *
+ * The union lives in core rather than the marketplace plugin because the
+ * console reasons about installed artifacts too — a Plugins index that cannot
+ * name an artifact type cannot render an update chip — and module boundaries
+ * (rightly) forbid an app depending on an addon lib. The marketplace model
+ * re-exports it, so publishing code still reads it from one place.
+ */ /**
+ * Install provenance (AGL-1015): where an installed artifact came from, at
+ * what version, and what it looked like when it arrived.
+ *
+ * Every install route used to stamp its own shape — plugins wrote a pin,
+ * dataset schemas a `source`, email templates an `installedFrom`, components a
+ * `marketplace` — and none of them kept the content as installed. Without the
+ * original there is no way to tell the publisher's change from the user's, so
+ * an update can only overwrite. This module defines the one shape all install
+ * routes write and the one reader everything else asks.
+ */ /**
+ * Immutable, content-addressed base snapshots — the content exactly as
+ * installed, keyed by its own hash and stored outside the user's edit path.
+ *
+ * Top-level rather than per-host on purpose: the same listing version installed
+ * onto twenty sites is one document, and re-installing it rewrites nothing.
+ */ export const ARTIFACT_BASE_COLLECTION = 'marketplaceArtifactBases';
+/**
+ * Firestore's per-document ceiling is 1 MiB. Snapshots are stored whole, so
+ * anything near it is refused rather than truncated — a partial base is worse
+ * than no base, because a diff would report the missing half as user edits.
+ */ export const ARTIFACT_BASE_MAX_BYTES = 800 * 1024;
+const UNKNOWN_PROVENANCE = {
+    state: 'unknown',
+    listingId: null,
+    version: null,
+    sha256: null,
+    artifactType: null,
+    publisherOrgId: null,
+    updatable: false
+};
+function asVersion(value) {
+    return value == null || value === '' ? null : String(value);
+}
+/**
+ * Reads provenance off an installed document, tolerating every shape the
+ * install routes wrote before AGL-1015.
+ *
+ * The legacy fields are read rather than migrated: a batch backfill could only
+ * ever recover the listing id and version, which is exactly what this recovers
+ * lazily, and it cannot invent a base snapshot. Installs re-stamp themselves
+ * properly the next time they are updated.
+ */ export function resolveProvenance(doc, fallbackArtifactType) {
+    var _doc_marketplace_profileId, _doc_profileId, _doc_sha256;
+    var _doc_marketplace, _doc_source;
+    if (!doc) return UNKNOWN_PROVENANCE;
+    const stamped = doc.installedFrom;
+    // A full stamp is the only thing that carries a base snapshot. Email
+    // templates have written a partial `installedFrom` since AGL-789, so the
+    // discriminator is the hash and the artifact type, not the field's presence.
+    if ((stamped == null ? void 0 : stamped.listingId) && stamped.sha256 && stamped.artifactType) {
+        var _stamped_publisherOrgId;
+        return {
+            state: 'recorded',
+            listingId: stamped.listingId,
+            version: asVersion(stamped.version),
+            sha256: stamped.sha256,
+            artifactType: stamped.artifactType,
+            publisherOrgId: (_stamped_publisherOrgId = stamped.publisherOrgId) != null ? _stamped_publisherOrgId : null,
+            updatable: true
+        };
+    }
+    const legacy = (stamped == null ? void 0 : stamped.listingId) ? {
+        listingId: stamped.listingId,
+        version: stamped.version,
+        profileId: null
+    } : ((_doc_marketplace = doc.marketplace) == null ? void 0 : _doc_marketplace.listingId) ? {
+        listingId: doc.marketplace.listingId,
+        version: doc.marketplace.version,
+        profileId: (_doc_marketplace_profileId = doc.marketplace.profileId) != null ? _doc_marketplace_profileId : null
+    } : ((_doc_source = doc.source) == null ? void 0 : _doc_source.listingId) ? {
+        listingId: doc.source.listingId,
+        version: doc.source.version,
+        profileId: null
+    } : // doc itself. It is the one artifact that never needed a snapshot —
+    // the bytes are immutable and content-addressed already — so a pin
+    // resolves as fully recorded.
+    doc.listingId ? {
+        listingId: doc.listingId,
+        version: doc.version,
+        profileId: (_doc_profileId = doc.profileId) != null ? _doc_profileId : null
+    } : null;
+    if (!legacy) return UNKNOWN_PROVENANCE;
+    const isPin = Boolean(doc.pluginId && doc.sha256);
+    return {
+        state: isPin ? 'recorded' : 'inferred',
+        listingId: legacy.listingId,
+        version: asVersion(legacy.version),
+        sha256: (_doc_sha256 = doc.sha256) != null ? _doc_sha256 : null,
+        artifactType: isPin ? 'plugin' : fallbackArtifactType != null ? fallbackArtifactType : null,
+        publisherOrgId: legacy.profileId,
+        updatable: isPin
+    };
+}
+/**
+ * Deterministic JSON with object keys in sorted order, so the same content
+ * hashes to the same id no matter what order Firestore handed the fields back.
+ *
+ * `undefined` members are dropped exactly as `JSON.stringify` drops them, which
+ * keeps `{a: 1}` and `{a: 1, b: undefined}` — the same document after a
+ * Firestore round-trip — hashing alike.
+ */ export function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value != null ? value : null);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry)=>stableStringify(entry)).join(',')}]`;
+    }
+    const entries = Object.entries(value).filter(([, entryValue])=>entryValue !== undefined).sort(([a], [b])=>a < b ? -1 : a > b ? 1 : 0).map(([key, entryValue])=>`${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}
+
+//# sourceMappingURL=marketplace-provenance.js.map

package/src/lib/app-utils/marketplace-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/marketplace-provenance.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 * Everything an org can publish to the marketplace (AGL-654).\n *\n * The union lives in core rather than the marketplace plugin because the\n * console reasons about installed artifacts too — a Plugins index that cannot\n * name an artifact type cannot render an update chip — and module boundaries\n * (rightly) forbid an app depending on an addon lib. The marketplace model\n * re-exports it, so publishing code still reads it from one place.\n */\nexport type MarketplaceArtifactType =\n  | 'component'\n  | 'template'\n  | 'plugin'\n  | 'layout'\n  | 'datasetSchema'\n  | 'emailTemplate'\n  /**\n   * A campaign email design, installed as a new `kind: 'email'` screen.\n   *\n   * Distinct from `emailTemplate`, which is a design FOR one entry in the\n   * fixed transactional catalog and can only ever land on that same key. A\n   * starter belongs to no key: it is a blank-page replacement for the composer,\n   * so it installs as a new document and the tenant may install ten of them.\n   * Folding the two together would give one install button two behaviors and\n   * would make the catalog key an absent-field discriminator.\n   */\n  | 'emailStarter'\n  | 'theme'\n\n/**\n * Install provenance (AGL-1015): where an installed artifact came from, at\n * what version, and what it looked like when it arrived.\n *\n * Every install route used to stamp its own shape — plugins wrote a pin,\n * dataset schemas a `source`, email templates an `installedFrom`, components a\n * `marketplace` — and none of them kept the content as installed. Without the\n * original there is no way to tell the publisher's change from the user's, so\n * an update can only overwrite. This module defines the one shape all install\n * routes write and the one reader everything else asks.\n */\n\n/**\n * Immutable, content-addressed base snapshots — the content exactly as\n * installed, keyed by its own hash and stored outside the user's edit path.\n *\n * Top-level rather than per-host on purpose: the same listing version installed\n * onto twenty sites is one document, and re-installing it rewrites nothing.\n */\nexport const ARTIFACT_BASE_COLLECTION = 'marketplaceArtifactBases'\n\n/**\n * Firestore's per-document ceiling is 1 MiB. Snapshots are stored whole, so\n * anything near it is refused rather than truncated — a partial base is worse\n * than no base, because a diff would report the missing half as user edits.\n */\nexport const ARTIFACT_BASE_MAX_BYTES = 800 * 1024\n\n/** The provenance stamp written on every installed artifact (AGL-1015). */\nexport interface InstalledFrom {\n  listingId: string\n  /** The listing version installed, as a string; null when unversioned. */\n  version: string | null\n  /** Content hash of the base snapshot — the key into {@link ARTIFACT_BASE_COLLECTION}. */\n  sha256: string | null\n  artifactType: MarketplaceArtifactType\n  installedAt: unknown\n  /** The publishing org (`listing.profileId`, org-owned since AGL-652). */\n  publisherOrgId: string | null\n  /**\n   * What review said about THE VERSION INSTALLED, recorded at install time.\n   *\n   * Optional because six of the seven artifact types are auto-listed and have\n   * no verdict to record. Where it is written it is a fact about one version\n   * and is never recomputed from the listing afterwards: a listing that earns\n   * `reviewStatus: 'verified'` next month did not retroactively review the\n   * bytes installed today, and a surface that resolved assurance live would\n   * say it did. Stamping it is what keeps \"unreviewed\" from decaying into a\n   * silence a reader mistakes for approval.\n   */\n  assurance?: 'approved' | 'unreviewed' | 'rejected'\n}\n\n/**\n * How much is actually known about where an artifact came from.\n *\n * `inferred` exists because the marketplace shipped before this stamp did:\n * pre-AGL-1015 installs carry a listing id somewhere but no hash and no base.\n * Calling those `recorded` would let an update think it has an origin to merge\n * against; calling them `unknown` would throw away a listing id we really do\n * have. They are their own state, and the UI says \"installed before update\n * tracking\" rather than implying either.\n */\nexport type ProvenanceState = 'recorded' | 'inferred' | 'unknown'\n\nexport interface ResolvedProvenance {\n  state: ProvenanceState\n  listingId: string | null\n  version: string | null\n  sha256: string | null\n  artifactType: MarketplaceArtifactType | null\n  publisherOrgId: string | null\n  /**\n   * A base snapshot exists, so this artifact can be diffed and safely updated.\n   * False for everything installed before the stamp — and saying so plainly is\n   * the point: a merge built on a fabricated origin destroys work silently.\n   */\n  updatable: boolean\n}\n\nconst UNKNOWN_PROVENANCE: ResolvedProvenance = {\n  state: 'unknown',\n  listingId: null,\n  version: null,\n  sha256: null,\n  artifactType: null,\n  publisherOrgId: null,\n  updatable: false,\n}\n\nfunction asVersion(value: unknown): string | null {\n  return value == null || value === '' ? null : String(value)\n}\n\n/**\n * Reads provenance off an installed document, tolerating every shape the\n * install routes wrote before AGL-1015.\n *\n * The legacy fields are read rather than migrated: a batch backfill could only\n * ever recover the listing id and version, which is exactly what this recovers\n * lazily, and it cannot invent a base snapshot. Installs re-stamp themselves\n * properly the next time they are updated.\n */\nexport function resolveProvenance(\n  doc:\n    | {\n        installedFrom?: Partial<InstalledFrom> | null\n        /** Component installs (`hosts/{h}/components`). */\n        marketplace?: { listingId?: string; profileId?: string; version?: unknown } | null\n        /** Template, layout and dataset-schema installs. */\n        source?: { type?: string; listingId?: string; version?: unknown } | null\n        /** Plugin pins are their own provenance: the pin IS the version. */\n        pluginId?: string\n        listingId?: string\n        profileId?: string\n        version?: unknown\n        sha256?: string\n      }\n    | null\n    | undefined,\n  fallbackArtifactType?: MarketplaceArtifactType,\n): ResolvedProvenance {\n  if (!doc) return UNKNOWN_PROVENANCE\n\n  const stamped = doc.installedFrom\n  // A full stamp is the only thing that carries a base snapshot. Email\n  // templates have written a partial `installedFrom` since AGL-789, so the\n  // discriminator is the hash and the artifact type, not the field's presence.\n  if (stamped?.listingId && stamped.sha256 && stamped.artifactType) {\n    return {\n      state: 'recorded',\n      listingId: stamped.listingId,\n      version: asVersion(stamped.version),\n      sha256: stamped.sha256,\n      artifactType: stamped.artifactType as MarketplaceArtifactType,\n      publisherOrgId: stamped.publisherOrgId ?? null,\n      updatable: true,\n    }\n  }\n\n  const legacy = stamped?.listingId\n    ? { listingId: stamped.listingId, version: stamped.version, profileId: null }\n    : doc.marketplace?.listingId\n      ? {\n          listingId: doc.marketplace.listingId,\n          version: doc.marketplace.version,\n          profileId: doc.marketplace.profileId ?? null,\n        }\n      : doc.source?.listingId\n        ? {\n            listingId: doc.source.listingId,\n            version: doc.source.version,\n            profileId: null,\n          }\n        : // A plugin pin is flat: `{listingId, version, sha256}` on the install\n          // doc itself. It is the one artifact that never needed a snapshot —\n          // the bytes are immutable and content-addressed already — so a pin\n          // resolves as fully recorded.\n          doc.listingId\n          ? {\n              listingId: doc.listingId,\n              version: doc.version,\n              profileId: doc.profileId ?? null,\n            }\n          : null\n  if (!legacy) return UNKNOWN_PROVENANCE\n\n  const isPin = Boolean(doc.pluginId && doc.sha256)\n  return {\n    state: isPin ? 'recorded' : 'inferred',\n    listingId: legacy.listingId,\n    version: asVersion(legacy.version),\n    sha256: doc.sha256 ?? null,\n    artifactType: isPin ? 'plugin' : (fallbackArtifactType ?? null),\n    publisherOrgId: legacy.profileId,\n    updatable: isPin,\n  }\n}\n\n/**\n * Deterministic JSON with object keys in sorted order, so the same content\n * hashes to the same id no matter what order Firestore handed the fields back.\n *\n * `undefined` members are dropped exactly as `JSON.stringify` drops them, which\n * keeps `{a: 1}` and `{a: 1, b: undefined}` — the same document after a\n * Firestore round-trip — hashing alike.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value ?? null)\n  }\n  if (Array.isArray(value)) {\n    return `[${value.map((entry) => stableStringify(entry)).join(',')}]`\n  }\n  const entries = Object.entries(value as Record<string, unknown>)\n    .filter(([, entryValue]) => entryValue !== undefined)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`)\n  return `{${entries.join(',')}}`\n}\n"],"names":["ARTIFACT_BASE_COLLECTION","ARTIFACT_BASE_MAX_BYTES","UNKNOWN_PROVENANCE","state","listingId","version","sha256","artifactType","publisherOrgId","updatable","asVersion","value","String","resolveProvenance","doc","fallbackArtifactType","stamped","installedFrom","legacy","profileId","marketplace","source","isPin","Boolean","pluginId","stableStringify","JSON","stringify","Array","isArray","map","entry","join","entries","Object","filter","entryValue","undefined","sort","a","b","key"],"mappings":"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"}

package/src/lib/app-utils/marketplace-theme.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @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 type { HostTheme, HostThemeScheme } from '@aglyn/shared-data-types';
+import { type ArtifactOverride } from './marketplace-overrides';
+/**
+ * Publish-time validation for themes as a marketplace artifact (AGL-1020).
+ *
+ * A plugin bundle is validated because it is code and the risk is a
+ * compromised site. A theme is data, so the risk is different in kind but not
+ * in consequence: the failure mode is an unreadable or half-painted site, which
+ * a publisher cannot see from their own machine because their fonts are
+ * installed and their eyes already know what the text says.
+ *
+ * Both of the things that go wrong are mechanically checkable, so they are
+ * checked here rather than left to review:
+ *
+ * * **Completeness.** Light and dark are not one palette with a filter. A theme
+ *   that defines only light is half a theme, and installing it leaves every
+ *   dark-mode visitor on MUI's stock blue — which reads as the site being
+ *   broken, not as the theme being partial.
+ * * **Contrast.** Text on its background, and label on its button, are the two
+ *   pairs that make a site unusable when they are wrong. WCAG gives an exact
+ *   ratio, so "is this readable" has an answer rather than an opinion.
+ *
+ * Errors refuse the publish; warnings are shown and can be published past. The
+ * split is deliberate — a 3.9:1 heading is a judgement call a designer may
+ * legitimately win, but a theme with no dark scheme is not a complete artifact
+ * whoever is asking.
+ *
+ * Pure and MUI-free so the publish route, the console's pre-flight and the
+ * tests all reach the same verdict from the same code.
+ */
+export interface ThemeValidationIssue {
+    /** Dotted path into the theme, so the editor can focus the offending field. */
+    path: string;
+    message: string;
+}
+export interface ThemeValidation {
+    /** No errors. Warnings do not block. */
+    ok: boolean;
+    errors: ThemeValidationIssue[];
+    warnings: ThemeValidationIssue[];
+}
+/**
+ * WCAG AA for body text. The same 4.5 the accessibility audit uses, rather
+ * than a house number, so a theme that passes here passes there.
+ */
+export declare const CONTRAST_AA = 4.5;
+/**
+ * WCAG AA for large text (18pt+/14pt bold) and UI component boundaries. Button
+ * labels are judged against this rather than 4.5 because they are large, short
+ * and centred, and holding them to body-text contrast rejects palettes that are
+ * genuinely fine.
+ */
+export declare const CONTRAST_AA_LARGE = 3;
+/**
+ * Parses a CSS colour into sRGB channels, or null when it is not something we
+ * can reason about.
+ *
+ * `null` means "not checked", never "failed": a theme is free to use `color-mix`
+ * or a CSS variable, and refusing to publish because this parser is narrower
+ * than CSS would be a validator inventing a rule the platform does not have.
+ */
+export declare function parseColor(value: unknown): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * WCAG contrast ratio between two colours, or null when either is unparseable.
+ * Ranges 1 (identical) to 21 (black on white).
+ */
+export declare function contrastRatio(a: unknown, b: unknown): number | null;
+/**
+ * Validates a theme for publishing.
+ *
+ * The same function backs the console's pre-flight and the publish route: a
+ * publisher who is told "this will be refused" and then has it accepted (or the
+ * reverse) stops trusting either, so there is one verdict from one place.
+ */
+export declare function validateThemeForPublish(theme: HostTheme | null | undefined): ThemeValidation;
+/**
+ * The theme content as published — the artifact and nothing else.
+ *
+ * What goes in here is what "reset to the publisher's version" restores and
+ * what the update diff compares against, so it must hold no per-install data:
+ * a host document also carries `updatedAt`, `updatedBy` and whatever else the
+ * editor writes alongside, and any of those in the content would read as a user
+ * edit on the next diff.
+ *
+ * Empty branches are dropped so two themes that render identically also hash
+ * identically — `{fonts: []}` and `{}` must not produce two base snapshots.
+ */
+export declare function themeArtifactContent(theme: HostTheme | null | undefined): HostTheme;
+/**
+ * A short, human summary of what a theme actually contains, for the install
+ * confirmation and the listing card.
+ *
+ * Installing a theme replaces a site's visual identity, so the confirmation has
+ * to say what is about to change in terms someone recognises — "both schemes,
+ * 2 fonts, 4 component styles" — rather than showing them a JSON blob and
+ * asking them to agree to it.
+ */
+export declare function describeTheme(theme: HostTheme | null | undefined): string[];
+/**
+ * The field on a host document holding the site's theme override.
+ *
+ * A theme is a FIELD on the host, not a document of its own, so it cannot use
+ * `ARTIFACT_OVERRIDE_FIELD` — a host may one day override more than one thing,
+ * and a bare `overrides` would be the first to claim the name. The override
+ * layer is general precisely so a namespaced field works with it unchanged.
+ */
+export declare const THEME_OVERRIDE_FIELD = "themeOverride";
+/** A host document, as far as the theme layer is concerned. */
+export interface ThemeHostDocument {
+    theme?: HostTheme | null;
+    themeOverride?: unknown;
+    themeInstalledFrom?: {
+        sha256?: string | null;
+        listingId?: string;
+    } | null;
+}
+/** Reads the stored theme override off a host document, tolerating junk. */
+export declare function readThemeOverride(host: ThemeHostDocument | null | undefined): ArtifactOverride | undefined;
+/**
+ * The site's effective theme: the marketplace theme (or the site's own) with
+ * this site's overrides resolved over it.
+ *
+ * This is the MIDDLE and TOP of the three layers the issue describes. The
+ * bottom — the platform default — is applied further down by
+ * `HostThemeProvider`, which layers whatever this returns onto the brand base
+ * (AGL-1180) so a theme that omits a value still yields a complete theme
+ * rather than an undefined-shaped hole. Doing it there rather than here is not
+ * a detail: the default is a runtime MUI theme with FUNCTION style overrides
+ * that JSON cannot represent, so a "default" merged at this layer would be a
+ * lossy copy of the real one.
+ *
+ * Every surface that renders a site's appearance calls this — the tenant, all
+ * four besigner editors, and the document preview — because a theme that
+ * resolves differently in the editor than on the site is worse than one that
+ * does not resolve at all.
+ */
+export declare function resolveSiteTheme(host: ThemeHostDocument | null | undefined): HostTheme | undefined;
+/**
+ * Where a site's theme came from (AGL-2938).
+ *
+ * - `installed` — a marketplace theme. The site's edits are its override
+ *   patch over the publisher's version, which stays untouched and can still
+ *   take an update.
+ * - `custom` — the site's own theme, edited in place.
+ * - `default` — the platform default. The site stores nothing until it
+ *   changes something, and then only what it changed.
+ *
+ * One reading for every surface that needs it — the page that lays out the
+ * Theme section, a widget proposing a change there, and a generator deciding
+ * what its change will be stored as — so none of them can file a site under
+ * a different source than the save path does.
+ */
+export type HostThemeSource = 'installed' | 'custom' | 'default';
+export declare function hostThemeSource(host: ThemeHostDocument | null | undefined): HostThemeSource;
+/**
+ * Was this override authored against the theme currently installed?
+ *
+ * False after a theme swap, which is the whole reason `baseSha256` is recorded.
+ * Overrides deliberately SURVIVE a swap (the issue's call, and the right one —
+ * a brand colour still expresses intent when the theme underneath it changes)
+ * but surviving silently is what would surprise people, so every surface that
+ * shows an override can ask this and say so.
+ *
+ * True when there is no override, and when either side has no hash to compare:
+ * "we cannot tell" must not render as "these are stale".
+ */
+export declare function isOverrideForCurrentTheme(host: ThemeHostDocument | null | undefined): boolean;
+/** One row of the "what have I changed?" view. */
+export interface ThemeOverrideEntry {
+    /** Dotted path into the theme, e.g. `colorSchemes.dark.primary.main`. */
+    path: string;
+    /** A human label for the path, for a UI that is not a JSON viewer. */
+    label: string;
+    /** Which scheme this touches, when it touches one. */
+    scheme?: HostThemeScheme;
+    /** The publisher's value, or undefined when the override adds the field. */
+    themeValue: unknown;
+    /** What this site set it to, or undefined when the override removes it. */
+    overrideValue: unknown;
+}
+/**
+ * A readable label for a theme path.
+ *
+ * "Colour · dark · primary" beats `colorSchemes.dark.primary.main`, and the
+ * difference matters because this list is the answer to "what have I changed?"
+ * — a question nobody asks wanting to read JSON paths.
+ */
+export declare function describeThemePath(path: string): string;
+/**
+ * "What have I changed?" — the patch, rendered.
+ *
+ * Literally a read of the stored override rather than a diff computed at call
+ * time, which is the property the whole layer exists to provide: the answer is
+ * the thing that was saved, so it cannot disagree with what will be applied.
+ */
+export declare function describeThemeOverride(host: ThemeHostDocument | null | undefined): ThemeOverrideEntry[];
+/**
+ * The override this site should store after the theme editor produced `edited`.
+ *
+ * The editor edits the RESOLVED theme — that is what it renders and what the
+ * user sees — so the patch is the difference between the publisher's base and
+ * what came back. Diffing here rather than tracking per-field dirty state means
+ * a field the user set and then set back to the theme's value stops being an
+ * override, which is what "reset" means without needing a reset button to have
+ * been pressed.
+ */
+export declare function themeOverridePatch(host: ThemeHostDocument | null | undefined, edited: HostTheme): unknown;
+/**
+ * Where this site's overrides sit on top of values a theme update also changes
+ * — the only place a conflict can exist.
+ *
+ * Narrow by construction: an override touching four paths can conflict in at
+ * most four places however much of the theme the publisher rewrote. That is the
+ * difference between "the publisher also changed your heading colour, whose
+ * wins?" and "this update rewrites your theme, continue?".
+ */
+export declare function themeUpdateConflicts(host: ThemeHostDocument | null | undefined, incoming: HostTheme): ThemeOverrideEntry[];