gazetta 0.6.0 → 0.8.0

package/dist/targets.js

@@ -1,7 +1,4 @@
-import { resolve, join } from 'node:path';
-import { execSync } from 'node:child_process';
 import { isEditable } from './types.js';
-import { createFilesystemProvider } from './providers/filesystem.js';
 export class UnknownTargetError extends Error {
     constructor(name) {
         super(`Unknown target: ${name}`);
@@ -10,14 +7,15 @@ export class UnknownTargetError extends Error {
 }
 export class NoEditableTargetError extends Error {
     constructor() {
-        super('No editable target is configured. At least one target in site.yaml must be editable.');
+        super('No editable target is configured. At least one target in site.config.ts must be editable.');
         this.name = 'NoEditableTargetError';
     }
 }
 /**
  * Build a TargetRegistry from already-initialized providers and their configs.
- * The factory that boots the dev server populates `providers` by running
- * `createStorageProvider` per target; tests pass in-memory providers.
+ * Per Phase 1 (Path X), storage providers are constructed by operator-facing
+ * factories at config-eval time; the registry consumes the resulting
+ * `StorageProvider` instances directly. Tests pass in-memory providers.
  */
 export function createTargetRegistryView(providers, configs) {
     const orderedNames = Object.keys(configs);
@@ -50,115 +48,19 @@ export function listEditableTargets(configs) {
         .filter(([, cfg]) => isEditable(cfg))
         .map(([name]) => name);
 }
+/**
+ * Expand `${VAR}` placeholders in a string by reading from `process.env`.
+ * Empty or undefined input passes through. Used by purge-config resolution
+ * (`PurgeConfig.apiToken`, `zoneId`) where operators may reference env
+ * vars without writing `process.env.X!` directly. Storage credentials
+ * use `process.env.X!` at the factory call site (Path X) and don't go
+ * through this helper.
+ */
 export function resolveEnvVars(value) {
     if (!value)
         return value;
     return value.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? '');
 }
-/**
- * Build a storage provider from config.
- *
- * For filesystem targets, `path` defaults to `./targets/<targetName>` (relative
- * to the site dir). Users can override by setting `path` explicitly in
- * site.yaml — useful for shared drives, existing layouts, or multi-site setups
- * that need custom paths. If neither `path` nor `targetName` is available for
- * a filesystem target, throws.
- */
-export async function createStorageProvider(config, siteDir, targetName) {
-    switch (config.type) {
-        case 'filesystem': {
-            const path = config.path ?? (targetName ? join('targets', targetName) : undefined);
-            if (!path)
-                throw new Error('Filesystem storage requires "path" (or a target name to derive the default from)');
-            return createFilesystemProvider(resolve(siteDir, path));
-        }
-        case 'azure-blob': {
-            const connectionString = resolveEnvVars(config.connectionString);
-            if (!connectionString)
-                throw new Error('Azure Blob storage requires "connectionString"');
-            if (!config.container)
-                throw new Error('Azure Blob storage requires "container"');
-            try {
-                const { createAzureBlobProvider } = await import('./providers/azure-blob.js');
-                return createAzureBlobProvider({ connectionString, container: config.container });
-            }
-            catch {
-                throw new Error('Azure Blob storage requires @azure/storage-blob. Install it: npm install @azure/storage-blob');
-            }
-        }
-        case 's3': {
-            const endpoint = resolveEnvVars(config.endpoint);
-            if (!endpoint)
-                throw new Error('S3 storage requires "endpoint"');
-            if (!config.bucket)
-                throw new Error('S3 storage requires "bucket"');
-            try {
-                const { createS3Provider } = await import('./providers/s3.js');
-                return createS3Provider({
-                    endpoint,
-                    bucket: config.bucket,
-                    accessKeyId: resolveEnvVars(config.accessKeyId) ?? 'minioadmin',
-                    secretAccessKey: resolveEnvVars(config.secretAccessKey) ?? 'minioadmin',
-                    region: config.region,
-                });
-            }
-            catch {
-                throw new Error('S3 storage requires @aws-sdk/client-s3. Install it: npm install @aws-sdk/client-s3');
-            }
-        }
-        case 'r2': {
-            if (!config.accountId)
-                throw new Error('R2 storage requires "accountId"');
-            if (!config.bucket)
-                throw new Error('R2 storage requires "bucket"');
-            const accessKeyId = resolveEnvVars(config.accessKeyId);
-            const secretAccessKey = resolveEnvVars(config.secretAccessKey);
-            // When S3 credentials are available, use S3 provider (fast, parallel — good for CI)
-            if (accessKeyId && secretAccessKey) {
-                try {
-                    const { createS3Provider } = await import('./providers/s3.js');
-                    return createS3Provider({
-                        endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
-                        bucket: config.bucket,
-                        accessKeyId,
-                        secretAccessKey,
-                        region: config.region,
-                    });
-                }
-                catch {
-                    throw new Error('R2 with S3 credentials requires @aws-sdk/client-s3. Install it: npm install @aws-sdk/client-s3');
-                }
-            }
-            // Fall back to Cloudflare REST API using wrangler auth
-            let apiToken;
-            try {
-                const output = execSync('npx wrangler auth token', {
-                    encoding: 'utf-8',
-                    timeout: 10000,
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                });
-                // wrangler prints a banner before the token — extract the last non-empty line
-                apiToken =
-                    output
-                        .split('\n')
-                        .map(l => l.trim())
-                        .filter(l => l && !l.includes('wrangler') && !l.includes('───'))
-                        .pop() ?? '';
-            }
-            catch {
-                throw new Error('R2 storage: no credentials found.\n' +
-                    '  Either set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY environment variables,\n' +
-                    '  or run "npx wrangler login" to authenticate with Cloudflare.');
-            }
-            if (!apiToken)
-                throw new Error('R2 storage: wrangler returned empty token. Run "npx wrangler login" to authenticate.');
-            const { createR2RestProvider } = await import('./providers/r2.js');
-            return createR2RestProvider({ accountId: config.accountId, bucket: config.bucket, apiToken });
-        }
-        default:
-            throw new Error(`Unknown storage type: ${config.type}`);
-    }
-}
 /**
  * Per-target init timeout — guards against SDKs that hang on unreachable
  * endpoints instead of surfacing the connection error. 10s is generous for
@@ -166,17 +68,25 @@ export async function createStorageProvider(config, siteDir, targetName) {
  * missing local emulator doesn't wedge the dev server for long.
  */
 const TARGET_INIT_TIMEOUT_MS = 10000;
-export async function createTargetRegistry(targets, siteDir) {
+/**
+ * Initialize all target providers in parallel, calling each provider's
+ * optional `init()` method (used for connectivity probes by S3 / Azure).
+ * Returns a `Map<targetName, StorageProvider>` ready for
+ * `createTargetRegistryView`.
+ *
+ * Failed inits are logged and skipped — callers see a partial registry.
+ * Slow inits time out at `TARGET_INIT_TIMEOUT_MS` so a hanging SDK doesn't
+ * stall the whole boot.
+ */
+export async function createTargetRegistry(targets) {
     const registry = new Map();
-    // Init targets in parallel — a slow/failing target must not serialize
-    // behind the others. Each has its own timeout so a hang doesn't stall the
-    // registry indefinitely.
     await Promise.all(Object.entries(targets).map(async ([name, config]) => {
         try {
             const initOne = async () => {
-                const provider = await createStorageProvider(config.storage, siteDir, name);
-                if ('init' in provider && typeof provider.init === 'function') {
-                    await provider.init();
+                const provider = config.storage;
+                const initFn = provider.init;
+                if (typeof initFn === 'function') {
+                    await initFn.call(provider);
                 }
                 return provider;
             };

package/dist/targets.js.map

@@ -1 +1 @@
-{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"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"}

package/dist/testing/admin-cache-contract.d.ts

@@ -0,0 +1,52 @@
+import type { AdminCache } from '../cache/types.js';
+/**
+ * Factory shape — each test gets a fresh provider instance. Providers
+ * with module-level state should construct fresh per call so tests
+ * don't leak across each other.
+ */
+export type AdminCacheFactory = () => AdminCache | Promise<AdminCache>;
+export interface AdminCacheContractOptions {
+    /**
+     * Whether the provider honors TTL on `set(key, value, { ttl })`.
+     * Default false (matches `MemoryCache` v1's LRU-only eviction).
+     * When true, the suite includes a TTL-expiry test that waits for
+     * the configured `ttlSeconds` to elapse.
+     */
+    supportsTtl?: boolean;
+    /**
+     * TTL in seconds used by the TTL test. Default 1 second — long
+     * enough to be observable, short enough to keep the test fast.
+     * Only consulted when `supportsTtl` is true.
+     */
+    ttlSeconds?: number;
+    /**
+     * Whether `subscribe()` delivers events from a sibling instance
+     * (true for shared-backing providers like RedisCache after Cut 4
+     * of cache-impl ships SSE; false for single-instance MemoryCache
+     * v1). When true, the suite includes a cross-instance notification
+     * test.
+     */
+    supportsCrossInstanceSubscribe?: boolean;
+    /**
+     * Whether the provider fails open on transport errors per Universal
+     * Provider Requirement #5. Tests a synthetic transport failure
+     * surfaced via a wrapper; only meaningful for providers that have
+     * a transport layer (Redis, Azure). MemoryCache has no transport.
+     */
+    supportsTransportFailureSimulation?: boolean;
+}
+/**
+ * Run the contract suite against a provider factory. Call from a
+ * `describe` block in the provider's own test file:
+ *
+ *   import { adminCacheContractTests } from 'gazetta/testing'
+ *
+ *   describe('RedisCache', () => {
+ *     adminCacheContractTests(
+ *       () => createRedisCache({ url: 'redis://localhost:6379' }),
+ *       { supportsTtl: true, supportsCrossInstanceSubscribe: true },
+ *     )
+ *   })
+ */
+export declare function adminCacheContractTests(factory: AdminCacheFactory, options?: AdminCacheContractOptions): void;
+//# sourceMappingURL=admin-cache-contract.d.ts.map

package/dist/testing/admin-cache-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-cache-contract.d.ts","sourceRoot":"","sources":["../../src/testing/admin-cache-contract.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAEtE,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC;;;;;OAKG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAA;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,GAAE,yBAA8B,GAAG,IAAI,CAsKjH"}

package/dist/testing/admin-cache-contract.js

@@ -0,0 +1,203 @@
+/**
+ * Contract tests for `AdminCache` providers, exported from
+ * `gazetta/testing`.
+ *
+ * Plugin authors and future built-in providers (RedisCache,
+ * AzureCache, FileCache, IndexedDBCache, etc.) run this suite
+ * against their implementation. The helper proves baseline LSP
+ * correctness — every provider must round-trip values, isolate
+ * keys, support prefix invalidation, and report honest stats.
+ *
+ * Capability-specific behaviors (TTL expiry, cross-instance
+ * subscribe, transport fail-open) are gated by per-test opt-ins on
+ * the options object. Providers that don't support a capability skip
+ * those tests cleanly — no LSP lies.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "test the AdminCache contract." Provider
+ *     mechanics live with each provider; this helper exercises the
+ *     interface uniformly.
+ *   - LSP: every provider that opts in to the helper passes the same
+ *     baseline. Failures here mean the provider violates the contract,
+ *     not that the test is wrong.
+ *   - OCP: adding a new capability check (e.g., `etag` support when
+ *     `EtagCapableCache` ships) is one new option + one new test
+ *     block; no rewrite of existing tests.
+ *   - DIP: the helper depends on the `AdminCache` interface, not on
+ *     any specific provider.
+ *
+ * # Why this isn't a vitest snapshot test
+ *
+ * Cache stats are non-deterministic over time and providers vary in
+ * which optional fields they track. Snapshot tests would create a
+ * brittle coupling between every provider's stats() shape and a
+ * shared snapshot. Behavior assertions ("hits incremented after a
+ * get-hit") are stable across providers.
+ */
+import { describe, expect, it } from 'vitest';
+/**
+ * Run the contract suite against a provider factory. Call from a
+ * `describe` block in the provider's own test file:
+ *
+ *   import { adminCacheContractTests } from 'gazetta/testing'
+ *
+ *   describe('RedisCache', () => {
+ *     adminCacheContractTests(
+ *       () => createRedisCache({ url: 'redis://localhost:6379' }),
+ *       { supportsTtl: true, supportsCrossInstanceSubscribe: true },
+ *     )
+ *   })
+ */
+export function adminCacheContractTests(factory, options = {}) {
+    describe('AdminCache contract — get/set/invalidate', () => {
+        it('round-trips a value through get/set', async () => {
+            const cache = await factory();
+            await cache.set('item:home', { title: 'Home' });
+            expect(await cache.get('item:home')).toEqual({ title: 'Home' });
+        });
+        it('returns null on a miss', async () => {
+            const cache = await factory();
+            expect(await cache.get('item:never-set')).toBeNull();
+        });
+        it('preserves the JSON-serializable contract — strings round-trip', async () => {
+            const cache = await factory();
+            await cache.set('item:str', 'hello');
+            expect(await cache.get('item:str')).toBe('hello');
+        });
+        it('preserves arrays and nested objects', async () => {
+            const cache = await factory();
+            const value = { items: [1, 2, 3], nested: { a: { b: 'c' } } };
+            await cache.set('item:complex', value);
+            expect(await cache.get('item:complex')).toEqual(value);
+        });
+        it('overwrites an existing value', async () => {
+            const cache = await factory();
+            await cache.set('item:k', 'first');
+            await cache.set('item:k', 'second');
+            expect(await cache.get('item:k')).toBe('second');
+        });
+        it('invalidate removes a single key', async () => {
+            const cache = await factory();
+            await cache.set('item:a', 1);
+            await cache.set('item:b', 2);
+            await cache.invalidate('item:a');
+            expect(await cache.get('item:a')).toBeNull();
+            expect(await cache.get('item:b')).toBe(2);
+        });
+        it('invalidate is a no-op on a missing key', async () => {
+            const cache = await factory();
+            await expect(cache.invalidate('item:never-set')).resolves.toBeUndefined();
+        });
+    });
+    describe('AdminCache contract — invalidatePrefix', () => {
+        it('removes all keys matching the prefix', async () => {
+            const cache = await factory();
+            await cache.set('group-a:home', 1);
+            await cache.set('group-a:about', 2);
+            await cache.set('group-b:home', 3);
+            const cleared = await cache.invalidatePrefix('group-a:');
+            expect(cleared).toBe(2);
+            expect(await cache.get('group-a:home')).toBeNull();
+            expect(await cache.get('group-a:about')).toBeNull();
+            expect(await cache.get('group-b:home')).toBe(3);
+        });
+        it('returns 0 when no keys match', async () => {
+            const cache = await factory();
+            await cache.set('group-a:home', 1);
+            const cleared = await cache.invalidatePrefix('group-c:');
+            expect(cleared).toBe(0);
+        });
+        it('does not match sibling prefixes (trailing colon discipline)', async () => {
+            // `'pages:'` should NOT match `'pages-archived:'` — the trailing
+            // colon prevents that. Consumers that omit the trailing colon
+            // are responsible for the consequences.
+            const cache = await factory();
+            await cache.set('pages:home', 1);
+            await cache.set('pages-archived:home', 2);
+            const cleared = await cache.invalidatePrefix('pages:');
+            expect(cleared).toBe(1);
+            expect(await cache.get('pages-archived:home')).toBe(2);
+        });
+    });
+    describe('AdminCache contract — subscribe', () => {
+        it('returns a disposer that does not throw when called', async () => {
+            const cache = await factory();
+            const disposer = cache.subscribe(() => undefined);
+            expect(() => disposer()).not.toThrow();
+        });
+        it('disposer is idempotent', async () => {
+            const cache = await factory();
+            const disposer = cache.subscribe(() => undefined);
+            disposer();
+            expect(() => disposer()).not.toThrow();
+        });
+    });
+    describe('AdminCache contract — stats', () => {
+        it('returns the required floor when stats() is implemented', async () => {
+            const cache = await factory();
+            // stats is optional on the contract — providers that don't
+            // expose it skip this test entirely.
+            if (!cache.stats)
+                return;
+            const result = await cache.stats();
+            expect(result).toMatchObject({
+                hits: expect.any(Number),
+                misses: expect.any(Number),
+                size: expect.any(Number),
+            });
+        });
+        it('size reflects the number of stored entries', async () => {
+            const cache = await factory();
+            if (!cache.stats)
+                return;
+            await cache.set('item:a', 1);
+            await cache.set('item:b', 2);
+            const result = await cache.stats();
+            expect(result.size).toBeGreaterThanOrEqual(2);
+        });
+    });
+    if (options.supportsTtl) {
+        const ttlSeconds = options.ttlSeconds ?? 1;
+        describe('AdminCache contract — TTL', () => {
+            it(`expires entries after ${ttlSeconds}s`, async () => {
+                const cache = await factory();
+                await cache.set('item:ttl', 'value', { ttl: ttlSeconds });
+                // Wait slightly past the TTL boundary.
+                await new Promise(r => setTimeout(r, (ttlSeconds + 0.2) * 1000));
+                expect(await cache.get('item:ttl')).toBeNull();
+            });
+        });
+    }
+    if (options.supportsCrossInstanceSubscribe) {
+        describe('AdminCache contract — cross-instance subscribe', () => {
+            it('delivers invalidation events from a sibling instance', async () => {
+                const a = await factory();
+                const b = await factory();
+                const events = [];
+                b.subscribe(event => events.push({ prefix: event.prefix }));
+                await a.set('shared:k', 1);
+                await a.invalidatePrefix('shared:');
+                // Allow async fan-out (provider-specific transport latency).
+                await new Promise(r => setTimeout(r, 100));
+                expect(events.some(e => e.prefix.includes('shared:'))).toBe(true);
+            });
+        });
+    }
+    if (options.supportsTransportFailureSimulation) {
+        describe('AdminCache contract — fail-open', () => {
+            it('treats transport failure on get as a miss (returns null, no throw)', async () => {
+                // Providers that opt in must expose a way to inject a
+                // transport failure. The contract assertion: under failure,
+                // get must NOT throw and must return null. Providers
+                // implement the injection mechanism in their own test setup.
+                const cache = await factory();
+                // The factory closure is the operator's hook — opt-in
+                // providers wire the failure into the returned instance and
+                // the test exercises whatever the provider's docs say.
+                await expect(cache.get('item:transport-failure')).resolves.not.toThrow();
+            });
+        });
+    }
+}
+//# sourceMappingURL=admin-cache-contract.js.map

package/dist/testing/admin-cache-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-cache-contract.js","sourceRoot":"","sources":["../../src/testing/admin-cache-contract.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `gazetta/testing` — test helpers for plugin authors and contributors.
+ *
+ * Imports here pull in `vitest` as a peer dependency. Plugin authors
+ * who use this barrel must have vitest in their devDependencies.
+ *
+ * Why a separate subpath: keeps vitest off the main `gazetta` import
+ * graph, so production deployments never bundle test-only code.
+ */
+export { adminCacheContractTests, type AdminCacheContractOptions, type AdminCacheFactory, } from './admin-cache-contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,uBAAuB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,GACvB,MAAM,2BAA2B,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,11 @@
+/**
+ * `gazetta/testing` — test helpers for plugin authors and contributors.
+ *
+ * Imports here pull in `vitest` as a peer dependency. Plugin authors
+ * who use this barrel must have vitest in their devDependencies.
+ *
+ * Why a separate subpath: keeps vitest off the main `gazetta` import
+ * graph, so production deployments never bundle test-only code.
+ */
+export { adminCacheContractTests, } from './admin-cache-contract.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,uBAAuB,GAGxB,MAAM,2BAA2B,CAAA"}

package/dist/themes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Theme resolution — single source of truth for theme configuration.
+ *
+ * Mirrors `locale.ts` for the theme dimension. Themes are an asset-override
+ * axis introduced in v1: each asset can carry per-theme byte overrides
+ * (typically `light` / `dark`) that the resolver picks per render context.
+ *
+ * Single responsibility: given a `SiteManifest`, return the resolved theme
+ * settings (supported list, default). Validation rules. Nothing about
+ * assets, manifests, or rendering — those are the resolver's concern.
+ *
+ * # Why a separate module from locale.ts
+ *
+ * Themes and locales are peer dimensions in the abstract model but they
+ * have different ergonomics: locale codes are open (BCP 47, thousands of
+ * valid values), theme codes are closed by convention (typically two or
+ * three names per site). The resolution logic is similar enough to feel
+ * shared and different enough to warrant separate modules — extracting
+ * a shared "dimension config" abstraction would couple them in ways that
+ * hurt clarity.
+ */
+import type { SiteManifest, ThemesConfig } from './types.js';
+/** Resolved theme settings for a site. */
+export interface ResolvedThemes {
+    /** All supported theme names, normalized to lowercase. */
+    supported: string[];
+    /** The default theme name. */
+    default: string;
+}
+/**
+ * Validate a theme name as it would appear in storage / filenames.
+ *
+ * Strict on input — does NOT normalize. Mixed case, leading dots, etc.
+ * fail. Callers that want lenient parsing should `normalizeTheme` first
+ * and then check.
+ *
+ * Rejects:
+ *   - empty / whitespace
+ *   - dots (would collide with filename suffix scheme)
+ *   - any uppercase character (filenames must be normalized to lowercase
+ *     before reaching storage; uppercase reaching this validator is a bug)
+ *   - BCP 47 locale codes (would be ambiguous in filename composition —
+ *     `hero.asset.en.json` could be locale `en` or theme `en`)
+ */
+export declare function isValidTheme(theme: string): boolean;
+/** Normalize a theme name to lowercase for filenames. */
+export declare function normalizeTheme(theme: string): string;
+/**
+ * Resolve theme settings from a site manifest. Throws when the config is
+ * present but invalid (collision with locale codes, malformed names) so
+ * misconfiguration surfaces at boot rather than silently at render time.
+ *
+ * Returns `null` when `themes` is unset — that's the "no theme dimension
+ * for this site" signal. Asset overrides keyed by theme are rejected
+ * downstream when this is null.
+ */
+export declare function resolveSiteThemes(site: SiteManifest): ResolvedThemes | null;
+/**
+ * Subset themes to a config — used when a target overrides the site's theme
+ * set. Falls back to the site's resolved themes when the target doesn't
+ * narrow.
+ *
+ * v1 doesn't expose target-level theme override (assets are global to the
+ * site's theme set). The function is here for symmetry with locale
+ * resolution and future-proofs the API when targets may want to ship a
+ * subset (e.g. a target that only serves light mode).
+ */
+export declare function resolveTargetThemes(siteThemes: ResolvedThemes | null, override?: ThemesConfig): ResolvedThemes | null;
+//# sourceMappingURL=themes.d.ts.map

package/dist/themes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"themes.d.ts","sourceRoot":"","sources":["../src/themes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG5D,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,IAAI,CA8B3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,cAAc,GAAG,IAAI,CAGrH"}