@spacefast/common 0.0.2

package/dist/contracts/space-config.d.ts

@@ -0,0 +1,216 @@
+import { z } from "zod";
+export declare const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
+export declare const SPACE_CONFIG_ALIAS_FILES: readonly ["spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
+export declare const SPACE_CONFIG_ACCEPTED_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
+export declare const SPACE_CONFIG_RETIRED_FILES: readonly ["stattic.jsonc", "stattic.json"];
+export declare const SPACE_CONFIG_PRIVATE_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json", "stattic.jsonc", "stattic.json"];
+export declare const SPACE_CONFIG_CAPS: {
+    /** Max raw `sf.jsonc` size in bytes. */
+    readonly fileBytes: number;
+    /** Max stored/compiled space `config` overlay size in bytes (JSON-encoded). */
+    readonly overlayBytes: number;
+    /** Max `templates` entries. */
+    readonly templates: 100;
+    readonly metaTitleChars: 300;
+    readonly metaDescriptionChars: 1000;
+    readonly metaImageChars: 2000;
+    /** Max bytes per `inject` snippet. */
+    readonly injectSnippetBytes: number;
+    /** Max snippets per `inject` array. */
+    readonly injectSnippets: 16;
+};
+/** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
+export declare const SPACE_CONFIG_SCHEMA_URL: string;
+export declare const spaceBuildSettingsSchema: z.ZodObject<{
+    rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SpaceBuildSettings = z.infer<typeof spaceBuildSettingsSchema>;
+export declare const spaceConfigSchema: z.ZodObject<{
+    index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    fallback: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        status: z.ZodNumber;
+    }, z.core.$strip>]>>;
+    listing: z.ZodOptional<z.ZodBoolean>;
+    meta: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    superpowers: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        disable_all_injection: z.ZodOptional<z.ZodBoolean>;
+        googleAnalytics: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            measurementId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        googleTagManager: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            containerId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        javascriptTags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            code: z.ZodString;
+        }, z.core.$strip>>>;
+        tags: z.ZodOptional<z.ZodObject<{
+            inheritance: z.ZodOptional<z.ZodObject<{
+                inherited: z.ZodOptional<z.ZodBoolean>;
+                overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    tagId: z.ZodString;
+                    disabled: z.ZodDefault<z.ZodBoolean>;
+                    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        color: z.ZodOptional<z.ZodObject<{
+            palette: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                color: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        typography: z.ZodOptional<z.ZodObject<{
+            fontSizes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                size: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            fontFamily: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        spacing: z.ZodOptional<z.ZodObject<{
+            spacingScale: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                size: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    build: z.ZodOptional<z.ZodObject<{
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
+    inject: z.ZodOptional<z.ZodObject<{
+        head: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bodyEnd: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SpaceConfig = z.infer<typeof spaceConfigSchema>;
+export declare function spaceSuperpowersEnabled(config: SpaceConfig | null | undefined): boolean;
+export declare const spaceConfigFileSchema: z.ZodObject<{
+    index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    fallback: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        status: z.ZodNumber;
+    }, z.core.$strip>]>>;
+    listing: z.ZodOptional<z.ZodBoolean>;
+    meta: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    superpowers: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        disable_all_injection: z.ZodOptional<z.ZodBoolean>;
+        googleAnalytics: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            measurementId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        googleTagManager: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            containerId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        javascriptTags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            code: z.ZodString;
+        }, z.core.$strip>>>;
+        tags: z.ZodOptional<z.ZodObject<{
+            inheritance: z.ZodOptional<z.ZodObject<{
+                inherited: z.ZodOptional<z.ZodBoolean>;
+                overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    tagId: z.ZodString;
+                    disabled: z.ZodDefault<z.ZodBoolean>;
+                    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        color: z.ZodOptional<z.ZodObject<{
+            palette: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                color: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        typography: z.ZodOptional<z.ZodObject<{
+            fontSizes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                size: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            fontFamily: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        spacing: z.ZodOptional<z.ZodObject<{
+            spacingScale: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                slug: z.ZodString;
+                size: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    build: z.ZodOptional<z.ZodObject<{
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
+    inject: z.ZodOptional<z.ZodObject<{
+        head: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bodyEnd: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    $schema: z.ZodOptional<z.ZodString>;
+    space: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SpaceConfigFile = z.infer<typeof spaceConfigFileSchema>;
+/**
+ * The published JSON Schema artifact for `sf.jsonc`, generated from the
+ * zod file schema. Served at SPACE_CONFIG_SCHEMA_URL so editors and agents get
+ * autocomplete and validation.
+ */
+export declare function spaceConfigJsonSchema(): Record<string, unknown>;
+export declare function stripHiddenSpaceConfigKeys(schema: unknown): unknown;

package/dist/contracts/space-config.js

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { BRAND } from "../brand.js";
+import { spaceThemeSchema } from "./space-theme.js";
+export const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
+export const SPACE_CONFIG_ALIAS_FILES = [
+    "spacefast.jsonc",
+    "spacefast.json",
+    "sf.json",
+    ".sf/sf.json",
+    ".sf/config.jsonc",
+    ".sf/config.json",
+];
+export const SPACE_CONFIG_ACCEPTED_FILES = [
+    SPACE_CONFIG_CANONICAL_FILE,
+    ...SPACE_CONFIG_ALIAS_FILES,
+];
+export const SPACE_CONFIG_RETIRED_FILES = ["stattic.jsonc", "stattic.json"];
+export const SPACE_CONFIG_PRIVATE_FILES = [
+    ...SPACE_CONFIG_ACCEPTED_FILES,
+    ...SPACE_CONFIG_RETIRED_FILES,
+];
+// Config compiler parser-safety caps (internal-docs/platform.md "Config
+// compiler scale targets"): hard from launch, enforced by ONE shared validator
+// at every intake seam — finalize for the `sf.jsonc` file, request
+// validation for the API `config` overlay. Plan policy may LOWER these caps,
+// never raise them.
+export const SPACE_CONFIG_CAPS = {
+    /** Max raw `sf.jsonc` size in bytes. */
+    fileBytes: 256 * 1024,
+    /** Max stored/compiled space `config` overlay size in bytes (JSON-encoded). */
+    overlayBytes: 16 * 1024,
+    /** Max `templates` entries. */
+    templates: 100,
+    metaTitleChars: 300,
+    metaDescriptionChars: 1000,
+    metaImageChars: 2000,
+    /** Max bytes per `inject` snippet. */
+    injectSnippetBytes: 8 * 1024,
+    /** Max snippets per `inject` array. */
+    injectSnippets: 16,
+};
+/** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
+export const SPACE_CONFIG_SCHEMA_URL = `${BRAND.websiteOrigin}/schemas/sf.json`;
+export const spaceBuildSettingsSchema = z
+    .object({
+    rootDirectory: z.string().trim().min(1).nullable().optional(),
+    installDirectory: z.string().trim().min(1).nullable().optional(),
+    installCommand: z.string().trim().min(1).nullable().optional(),
+    buildCommand: z.string().trim().min(1).nullable().optional(),
+    outputDirectory: z.string().trim().min(1).nullable().optional(),
+    ignoredBuildCommand: z.string().trim().min(1).nullable().optional(),
+    frameworkPreset: z.string().trim().min(1).nullable().optional(),
+    platformPreset: z.string().trim().min(1).nullable().optional(),
+    allowUnsupportedPlatformFeatures: z.boolean().optional(),
+    timeoutSeconds: z.number().int().min(60).max(7200).optional(),
+})
+    .strict()
+    .describe("Remote build settings used by repository builds.");
+// SpaceConfig (internal-docs/platform.md "SpaceConfig"): the declarative
+// serving config — also the shape of `sf.jsonc` minus `$schema`/`space`.
+// Meta caps are the spec parser-safety numbers (title 300, description 1000,
+// image 2000); plan policy may lower them but never raise them.
+export const spaceConfigSchema = z.object({
+    index: z
+        .union([z.string().min(1), z.literal(false)])
+        .optional()
+        .describe("Directory index file; false disables index resolution."),
+    fallback: z
+        .union([
+        z.string().min(1),
+        z.object({
+            path: z.string().min(1).describe("Committed file served when no exact route matches."),
+            status: z.number().int().min(100).max(599).describe("Response status for the fallback."),
+        }),
+    ])
+        .optional()
+        .describe('Fallback document; "/index.html" means SPA. Default: nearest 404.html.'),
+    listing: z.boolean().optional().describe("Enable automatic directory listings."),
+    meta: z
+        .object({
+        title: z.string().min(1).max(SPACE_CONFIG_CAPS.metaTitleChars).optional(),
+        description: z.string().max(SPACE_CONFIG_CAPS.metaDescriptionChars).optional(),
+        image: z.string().max(SPACE_CONFIG_CAPS.metaImageChars).optional(),
+    })
+        .optional()
+        .describe("Listing/viewer/OG metadata."),
+    superpowers: z
+        .object({
+        enabled: z.boolean().optional().describe("Master switch for platform-managed injections."),
+        disable_all_injection: z
+            .boolean()
+            .optional()
+            .describe("When true, suppresses every platform-managed script/tag injection."),
+        googleAnalytics: z
+            .object({
+            enabled: z.boolean().optional(),
+            measurementId: z.string().trim().max(64).optional(),
+        })
+            .optional(),
+        googleTagManager: z
+            .object({
+            enabled: z.boolean().optional(),
+            containerId: z.string().trim().max(64).optional(),
+        })
+            .optional(),
+        javascriptTags: z
+            .array(z.object({
+            id: z.string().trim().max(128).optional(),
+            name: z.string().trim().max(160).optional(),
+            enabled: z.boolean().optional(),
+            code: z.string().max(SPACE_CONFIG_CAPS.injectSnippetBytes),
+        }))
+            .max(SPACE_CONFIG_CAPS.injectSnippets)
+            .optional(),
+        tags: z
+            .object({
+            inheritance: z
+                .object({
+                inherited: z.boolean().optional(),
+                overrides: z
+                    .array(z.object({
+                    tagId: z.string().trim().min(1),
+                    disabled: z.boolean().default(false),
+                    reason: z.string().trim().max(500).nullable().optional(),
+                }))
+                    .max(128)
+                    .optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    })
+        .optional()
+        .describe("Platform-managed built-ins and custom JavaScript snippets."),
+    templates: z
+        .array(z.string().min(1))
+        .max(SPACE_CONFIG_CAPS.templates)
+        .optional()
+        .describe("Files that receive {{ vars.NAME }} substitution at finalize."),
+    theme: spaceThemeSchema
+        .optional()
+        .describe("Platform-page theming: a validated preset subset of WordPress theme.json."),
+    build: spaceBuildSettingsSchema
+        .optional()
+        .describe("Default settings for remote repository builds."),
+    // Intentionally undescribed (hidden, experimental): enables the finalize-time
+    // build pipeline (internal-docs/build-pipeline-plan.md). Accepted without
+    // diagnostics; absent/false keeps today's behavior byte-for-byte.
+    experimental_gutenberg: z.boolean().optional(),
+    // Intentionally minimally described (hidden, experimental): static HTML
+    // snippets, honored only when `experimental_gutenberg` is true. Byte caps are
+    // enforced by the shared validator (inject_snippet_too_large / inject_invalid).
+    inject: z
+        .object({
+        head: z.array(z.string()).max(SPACE_CONFIG_CAPS.injectSnippets).optional(),
+        bodyStart: z.array(z.string()).max(SPACE_CONFIG_CAPS.injectSnippets).optional(),
+        bodyEnd: z.array(z.string()).max(SPACE_CONFIG_CAPS.injectSnippets).optional(),
+        noscript: z.array(z.string()).max(SPACE_CONFIG_CAPS.injectSnippets).optional(),
+    })
+        .optional(),
+});
+export function spaceSuperpowersEnabled(config) {
+    const superpowers = config?.superpowers;
+    return superpowers?.enabled !== false && superpowers?.disable_all_injection !== true;
+}
+// The `sf.jsonc` FILE shape (internal-docs/platform.md "Space
+// Configuration Files"): SpaceConfig plus the editor `$schema` pointer and the
+// optional `space` link (slug or `spc_` id) resolved by CLI/publish flows.
+// Routing never lives here — redirects/rewrites/proxies/headers stay
+// exclusively in `_redirects`/`_headers` (one way per concern).
+export const spaceConfigFileSchema = spaceConfigSchema.extend({
+    $schema: z
+        .string()
+        .optional()
+        .describe(`JSON Schema pointer for editor/agent validation (${SPACE_CONFIG_SCHEMA_URL}).`),
+    space: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional space link: a space slug or spc_ id this project publishes to."),
+});
+/**
+ * The published JSON Schema artifact for `sf.jsonc`, generated from the
+ * zod file schema. Served at SPACE_CONFIG_SCHEMA_URL so editors and agents get
+ * autocomplete and validation.
+ */
+export function spaceConfigJsonSchema() {
+    return stripHiddenSpaceConfigKeys({
+        ...z.toJSONSchema(spaceConfigFileSchema, { target: "draft-7", io: "input" }),
+        $id: SPACE_CONFIG_SCHEMA_URL,
+        title: "Spacefast space configuration (sf.jsonc)",
+    });
+}
+/*
+ * Hidden-feature discipline (internal-docs/build-pipeline-plan.md): the
+ * `experimental_gutenberg` flag and its `inject` companion are ACCEPTED by the
+ * parser but never published — the bare key names alone would document the
+ * feature to every editor/agent reading a schema artifact. Every generator
+ * that derives a public artifact from the SpaceConfig zod shape (the
+ * sf.jsonc JSON Schema, the www publish-spec, the SDK OpenAPI documents)
+ * must run it through this stripper. The published schemas set no
+ * additionalProperties constraint, so configs that use the hidden keys still
+ * validate cleanly. `inject` is removed only when it carries the SpaceConfig
+ * static-placement shape so unrelated properties of the same name survive.
+ */
+export function stripHiddenSpaceConfigKeys(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map(stripHiddenSpaceConfigKeys);
+    }
+    if (!schema || typeof schema !== "object") {
+        return schema;
+    }
+    return Object.fromEntries(Object.entries(schema).map(([key, entry]) => {
+        if (key === "properties" && entry && typeof entry === "object" && !Array.isArray(entry)) {
+            const kept = Object.fromEntries(Object.entries(entry).filter(([name, value]) => {
+                if (name === "experimental_gutenberg") {
+                    return false;
+                }
+                return !(name === "inject" && isHiddenInjectShape(value));
+            }));
+            return [key, stripHiddenSpaceConfigKeys(kept)];
+        }
+        return [key, stripHiddenSpaceConfigKeys(entry)];
+    }));
+}
+function isHiddenInjectShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const properties = value.properties;
+    if (!properties || typeof properties !== "object" || Array.isArray(properties)) {
+        return false;
+    }
+    const keys = Object.keys(properties);
+    return (keys.length > 0 &&
+        keys.every((key) => key === "head" || key === "bodyStart" || key === "bodyEnd" || key === "noscript"));
+}

package/dist/contracts/space-theme.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const spaceThemeSchema: z.ZodObject<{
+    color: z.ZodOptional<z.ZodObject<{
+        palette: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            color: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    typography: z.ZodOptional<z.ZodObject<{
+        fontSizes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            size: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    spacing: z.ZodOptional<z.ZodObject<{
+        spacingScale: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            size: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SpaceTheme = z.infer<typeof spaceThemeSchema>;

package/dist/contracts/space-theme.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+// SpaceTheme (internal-docs/platform.md "SpaceTheme"): a validated preset
+// subset of WordPress theme.json. Presets only — no arbitrary CSS. The
+// finalize-time compiler (wave B1) additionally validates every value against
+// the safe-value grammar (no url()/@import/expression()/data: URIs) and drops
+// invalid keys with a warning diagnostic.
+const presetSlug = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9-]+$/, { message: "Preset slugs are lowercase alphanumerics and dashes." });
+export const spaceThemeSchema = z.object({
+    color: z
+        .object({
+        palette: z
+            .array(z.object({
+            slug: presetSlug,
+            color: z.string().min(1).max(128),
+            name: z.string().min(1).max(128).optional(),
+        }))
+            .max(64)
+            .optional(),
+    })
+        .optional(),
+    typography: z
+        .object({
+        fontSizes: z
+            .array(z.object({
+            slug: presetSlug,
+            size: z.string().min(1).max(64),
+            name: z.string().min(1).max(128).optional(),
+        }))
+            .max(64)
+            .optional(),
+        fontFamily: z.string().min(1).max(256).optional(),
+    })
+        .optional(),
+    spacing: z
+        .object({
+        spacingScale: z
+            .array(z.object({
+            slug: presetSlug,
+            size: z.string().min(1).max(64),
+        }))
+            .max(64)
+            .optional(),
+    })
+        .optional(),
+});