@takuhon/core 1.0.0 → 1.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 var $schema = "https://json-schema.org/draft/2020-12/schema";
-var $id = "https://takuhon.example/schemas/1.0.0/takuhon.schema.json";
+var $id = "https://takuhon.example/schemas/1.3.0/takuhon.schema.json";
 var title = "Takuhon Profile";
 var description = "Portable profile data format consumed by @takuhon/core. The canonical contract for profile content authored as takuhon.json.";
 var type = "object";
@@ -496,6 +496,26 @@ var $defs = {
 			}
 		}
 	},
+	SkillCategory: {
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"id",
+			"label"
+		],
+		properties: {
+			id: {
+				type: "string",
+				minLength: 1,
+				maxLength: 64,
+				description: "Matches the `category` value on the skills that belong to this group."
+			},
+			label: {
+				$ref: "#/$defs/LocalizedTitle",
+				description: "Localized display heading for the group."
+			}
+		}
+	},
 	Contact: {
 		type: "object",
 		additionalProperties: false,
@@ -566,6 +586,118 @@ var $defs = {
 			},
 			publicVisibility: {
 				$ref: "#/$defs/PublicVisibility"
+			},
+			contact: {
+				$ref: "#/$defs/ContactSettings"
+			},
+			appearance: {
+				$ref: "#/$defs/AppearanceSettings"
+			},
+			skillCategories: {
+				type: "array",
+				maxItems: 50,
+				items: {
+					$ref: "#/$defs/SkillCategory"
+				},
+				description: "Ordered skill-category display groups (added in 1.3.0). When present, the rendered profile groups skills by their `category` under these localized headings, in array order; absent = the flat skill list. A skill whose `category` is not listed here (or which has none) renders in a trailing group so nothing is dropped."
+			}
+		}
+	},
+	AppearanceSettings: {
+		type: "object",
+		additionalProperties: false,
+		description: "Opt-in design tokens for the rendered profile (added in 1.2.0). A declarative re-skin seam: owners override the standard renderer's built-in color and font defaults. This is a token map only, not arbitrary CSS — every value is length- and pattern-constrained so it cannot break out of the inline <style>. Overriding tokens re-skins the page but cannot re-layout it (spacing/radius/type-scale are intentionally not exposed). Absent = the built-in defaults are used unchanged.",
+		properties: {
+			fontFamily: {
+				type: "string",
+				minLength: 1,
+				maxLength: 256,
+				pattern: "^[A-Za-z0-9\\s,'\"._-]+$",
+				description: "CSS font-family stack for the page body, e.g. \"Inter, system-ui, sans-serif\". Quotes and commas are allowed; CSS-structural characters (; { } < >) are not."
+			},
+			colors: {
+				$ref: "#/$defs/AppearanceColors",
+				description: "Light-mode (:root) color overrides."
+			},
+			colorsDark: {
+				$ref: "#/$defs/AppearanceColors",
+				description: "Dark-mode (prefers-color-scheme: dark) color overrides. Note: until the standard renderer ships a default dark palette, only the keys set here change in dark mode."
+			}
+		}
+	},
+	AppearanceColors: {
+		type: "object",
+		additionalProperties: false,
+		description: "A set of overridable color tokens. Each value is a CSS color (hex, rgb()/rgba(), hsl()/hsla(), or a named color); CSS-structural characters (; { } < > \" ' \\) are disallowed so a value cannot escape the inline <style>.",
+		properties: {
+			bg: {
+				$ref: "#/$defs/CssColor",
+				description: "Page background."
+			},
+			surface: {
+				$ref: "#/$defs/CssColor",
+				description: "Raised surfaces such as skill/tag chips."
+			},
+			text: {
+				$ref: "#/$defs/CssColor",
+				description: "Primary body text."
+			},
+			textMuted: {
+				$ref: "#/$defs/CssColor",
+				description: "Secondary/muted text (taglines, meta, captions)."
+			},
+			border: {
+				$ref: "#/$defs/CssColor",
+				description: "Hairline borders and rules."
+			},
+			accent: {
+				$ref: "#/$defs/CssColor",
+				description: "Accent color for emphasis and focus affordances."
+			},
+			primary: {
+				$ref: "#/$defs/CssColor",
+				description: "Primary interactive color, e.g. links."
+			},
+			primaryContrast: {
+				$ref: "#/$defs/CssColor",
+				description: "Foreground color used on top of the primary color."
+			}
+		}
+	},
+	CssColor: {
+		type: "string",
+		minLength: 1,
+		maxLength: 64,
+		pattern: "^(?:#[0-9A-Fa-f]{3,8}|[A-Za-z]+|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\\([A-Za-z0-9.,%/\\s-]*\\))$",
+		description: "A CSS color value, restricted to a safe allowlist: a hex color (#rgb/#rgba/#rrggbb/#rrggbbaa), a bare keyword (named colors, currentColor, transparent), or a color function (rgb/rgba/hsl/hsla/hwb/lab/lch/oklab/oklch/color). url(), image-set(), var(), and other fetch- or reference-bearing functions are intentionally excluded so a value can never trigger an external request or escape the inline <style>."
+	},
+	ContactSettings: {
+		type: "object",
+		additionalProperties: false,
+		description: "Opt-in contact form configuration (added in 1.1.0). Only public values live here; the Turnstile site key is safe to embed in the page. The Turnstile secret, the recipient address, and the From label are provisioned out of band as environment configuration and are never stored in takuhon.json. Adapters that support the form mount the widget and a POST endpoint when 'enabled' is true.",
+		properties: {
+			enabled: {
+				type: "boolean",
+				"default": false,
+				description: "Master switch. When false (the default), no contact form is mounted even if a site key is present."
+			},
+			turnstileSiteKey: {
+				type: "string",
+				minLength: 1,
+				maxLength: 128,
+				description: "Public Cloudflare Turnstile site key, safe to embed in the page. Without it the widget is not mounted."
+			},
+			endpoint: {
+				type: "string",
+				minLength: 1,
+				maxLength: 2048,
+				description: "Override the POST endpoint the widget submits to. Defaults to /api/contact on the same origin."
+			},
+			subjectPrefix: {
+				type: "string",
+				minLength: 1,
+				maxLength: 128,
+				description: "Subject prefix for the delivered email, e.g. '[example.com contact]'."
 			}
 		}
 	},
@@ -1814,6 +1946,23 @@ declare const schema: {
                 };
             };
         };
+        SkillCategory: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                label: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+        };
         Contact: {
             type: string;
             additionalProperties: boolean;
@@ -1882,6 +2031,118 @@ declare const schema: {
                 publicVisibility: {
                     $ref: string;
                 };
+                contact: {
+                    $ref: string;
+                };
+                appearance: {
+                    $ref: string;
+                };
+                skillCategories: {
+                    type: string;
+                    maxItems: number;
+                    items: {
+                        $ref: string;
+                    };
+                    description: string;
+                };
+            };
+        };
+        AppearanceSettings: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            properties: {
+                fontFamily: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    pattern: string;
+                    description: string;
+                };
+                colors: {
+                    $ref: string;
+                    description: string;
+                };
+                colorsDark: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+        };
+        AppearanceColors: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            properties: {
+                bg: {
+                    $ref: string;
+                    description: string;
+                };
+                surface: {
+                    $ref: string;
+                    description: string;
+                };
+                text: {
+                    $ref: string;
+                    description: string;
+                };
+                textMuted: {
+                    $ref: string;
+                    description: string;
+                };
+                border: {
+                    $ref: string;
+                    description: string;
+                };
+                accent: {
+                    $ref: string;
+                    description: string;
+                };
+                primary: {
+                    $ref: string;
+                    description: string;
+                };
+                primaryContrast: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+        };
+        CssColor: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+            description: string;
+        };
+        ContactSettings: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            properties: {
+                enabled: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                turnstileSiteKey: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                endpoint: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                subjectPrefix: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
             };
         };
         PublicVisibility: {
@@ -2921,6 +3182,91 @@ interface Settings {
     activity?: ActivitySettings;
     /** Per-section public visibility (added in 0.6.0). Absent = all sections visible. */
     publicVisibility?: PublicVisibility;
+    /** Opt-in contact form (added in 1.1.0). Absent = no contact form. */
+    contact?: ContactSettings;
+    /** Opt-in design tokens for the rendered profile (added in 1.2.0). Absent = built-in defaults. */
+    appearance?: AppearanceSettings;
+    /**
+     * Ordered skill-category display groups (added in 1.3.0). When present, the
+     * rendered profile groups skills by their `category` under these localized
+     * headings, in array order; absent = the flat skill list. A skill whose
+     * `category` is unlisted (or absent) renders in a trailing group.
+     */
+    skillCategories?: SkillCategory[];
+}
+/**
+ * One skill-category display group (added in 1.3.0). Maps a `Skill.category`
+ * value to a localized heading; the array position in {@link
+ * Settings.skillCategories} defines the group's display order.
+ */
+interface SkillCategory {
+    /** Matches the `category` value on the skills that belong to this group. */
+    id: string;
+    /** Localized display heading for the group. */
+    label: LocalizedTitle;
+}
+/**
+ * Opt-in design tokens for the rendered profile (added in 1.2.0).
+ *
+ * A declarative re-skin seam: owners override the standard renderer's built-in
+ * color and font defaults. This is a token map only — never arbitrary CSS — so
+ * every value is length- and pattern-constrained (see the schema) and cannot
+ * break out of the inline `<style>`. Overriding tokens re-skins the page but
+ * cannot re-layout it; spacing, radius, and the type scale are intentionally
+ * not exposed. An absent block leaves the built-in defaults unchanged.
+ */
+interface AppearanceSettings {
+    /** CSS font-family stack for the page body, e.g. `"Inter, system-ui, sans-serif"`. */
+    fontFamily?: string;
+    /** Light-mode (`:root`) color overrides. */
+    colors?: AppearanceColors;
+    /**
+     * Dark-mode (`prefers-color-scheme: dark`) color overrides. Until the
+     * standard renderer ships a default dark palette, only the keys set here
+     * change in dark mode.
+     */
+    colorsDark?: AppearanceColors;
+}
+/**
+ * Overridable color tokens (added in 1.2.0). Each value is a CSS color (hex,
+ * `rgb()`/`rgba()`, `hsl()`/`hsla()`, or a named color); CSS-structural
+ * characters are disallowed so a value cannot escape the inline `<style>`.
+ */
+interface AppearanceColors {
+    /** Page background. */
+    bg?: string;
+    /** Raised surfaces such as skill/tag chips. */
+    surface?: string;
+    /** Primary body text. */
+    text?: string;
+    /** Secondary/muted text (taglines, meta, captions). */
+    textMuted?: string;
+    /** Hairline borders and rules. */
+    border?: string;
+    /** Accent color for emphasis and focus affordances. */
+    accent?: string;
+    /** Primary interactive color, e.g. links. */
+    primary?: string;
+    /** Foreground color used on top of the primary color. */
+    primaryContrast?: string;
+}
+/**
+ * Owner-curated configuration for the opt-in contact form (added in 1.1.0).
+ * Only public values live here: the Turnstile **site key** is safe to embed in
+ * the page. The Turnstile secret, the recipient address, and the From label are
+ * provisioned out of band as environment configuration and are never stored in
+ * `takuhon.json`. Adapters that support the form mount the widget and a POST
+ * endpoint when {@link enabled} is true; adapters that do not simply ignore it.
+ */
+interface ContactSettings {
+    /** Master switch; no contact form is mounted when false (the default). */
+    enabled?: boolean;
+    /** Public Cloudflare Turnstile site key, safe to embed; required to mount the widget. */
+    turnstileSiteKey?: string;
+    /** Override the POST endpoint the widget submits to. Defaults to `/api/contact` (same origin). */
+    endpoint?: string;
+    /** Subject prefix for the delivered email, e.g. `"[example.com contact]"`. */
+    subjectPrefix?: string;
 }
 /**
  * Per-section public/private visibility (added in 0.6.0).
@@ -3253,13 +3599,31 @@ interface LocalizedRecommendation extends VisibilityControlled {
     relatedEducationId?: Slug;
     order?: number;
 }
+/**
+ * One skill-category group after locale resolution: the localized `label` map
+ * collapsed to the single resolved string. See {@link SkillCategory}.
+ */
+interface LocalizedSkillCategory {
+    id: string;
+    label: string;
+}
+/**
+ * {@link Settings} after locale resolution. Identical to the raw settings
+ * except `skillCategories` labels are collapsed to single resolved strings
+ * ({@link LocalizedSkillCategory}); every other settings field is passed
+ * through unchanged.
+ */
+type LocalizedSettings = Omit<Settings, 'skillCategories'> & {
+    skillCategories?: LocalizedSkillCategory[];
+};
 /**
  * A takuhon document with every localized map flattened to a single string,
  * plus a `resolvedLocale` field recording which tag was actually used as the
  * head of the fallback chain. `resolveLocale()` returns this shape.
  *
- * `Skill`, `Contact`, `Settings`, and `Meta` carry no localized fields and
- * pass through unchanged.
+ * `Skill`, `Contact`, and `Meta` carry no localized fields and pass through
+ * unchanged; `Settings` passes through too, except its `skillCategories`
+ * labels are resolved to the single locale string (see {@link LocalizedSettings}).
  */
 interface LocalizedTakuhon {
     schemaVersion: string;
@@ -3280,7 +3644,7 @@ interface LocalizedTakuhon {
     testScores: LocalizedTestScore[];
     recommendations: LocalizedRecommendation[];
     contact: Contact;
-    settings: Settings;
+    settings: LocalizedSettings;
     meta: Meta;
     /**
      * The locale tag that was matched first by the fallback chain and used as
@@ -3326,7 +3690,7 @@ interface LocalizedTakuhon {
  * versions whose JSON Schema this package literally bundles, not the full
  * support window seen by end users.
  */
-declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0", "1.0.0"];
+declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0", "1.0.0", "1.1.0", "1.2.0", "1.3.0"];
 /**
  * A single validation failure.
  *
@@ -4456,6 +4820,6 @@ declare function stripImageMetadata(bytes: Uint8Array, mime: AcceptedImageMime):
  * A takuhon profile document's `schemaVersion` field must be migrate-compatible
  * with this version. See operational-lifecycle docs for the migration policy.
  */
-declare const SCHEMA_VERSION = "1.0.0";
+declare const SCHEMA_VERSION = "1.3.0";
 
-export { ACCEPTED_IMAGE_MIME_TYPES, type AcceptedImageMime, type ActivitySettings, type ActivitySnapshot, type ActivityStorage, type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, type CodingTime, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type ContributionCalendar, type ContributionDay, type Course, type CvDocument, type CvHeader, type CvSection, type CvSectionKind, DARK_PALETTE, type Education, type ExportOptions, type ExportedTakuhon, type GravatarOptions, type Honor, IMAGE_EXTENSIONS, type ImageInfo, ImportError, type Iso3166Alpha2, type IsoDateTime, LIGHT_PALETTE, type Language, type LanguageBreakdown, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedRecommendation, type LocalizedRecommendationAuthor, type LocalizedTakuhon, type LocalizedTestScore, type LocalizedTitle, type LocalizedVolunteering, MAX_IMAGE_BYTES, MAX_IMAGE_DIMENSION, MAX_IMAGE_FRAMES, MCP_PROFILE_SECTIONS, MCP_RESOURCES, MCP_TOOLS, type McpInputSchema, type McpProfileSection, McpRequestError, type McpResourceDefinition, type McpResourceResult, type McpToolDefinition, type McpToolResult, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Palette, type Patent, type PatentStatus, type Profile, type Project, type PublicVisibility, type Publication, RANK_FULL_CODING_HOURS, RANK_FULL_CONTRIBUTIONS, RANK_TIER_THRESHOLDS, type RankInput, type RankTier, type RankTierLabel, type Recommendation, type RecommendationAuthor, type RenderActivitySvgOptions, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type TestScore, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, applyPublicPrivacyFilter, computeLanguagePercentages, deriveCv, deriveRankTier, detectImageMime, executeMcpTool, exportTakuhon, formatCodingTime, formatDate, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, getPresentLabel, gravatarUrl, importTakuhon, isActivitySnapshot, migrateTakuhon, migrations, normalize, readImageInfo, readMcpResource, renderActivitySvg, resolveLocale, schema, stripImageMetadata, validate };
+export { ACCEPTED_IMAGE_MIME_TYPES, type AcceptedImageMime, type ActivitySettings, type ActivitySnapshot, type ActivityStorage, type Address, type AppearanceColors, type AppearanceSettings, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, type CodingTime, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type ContributionCalendar, type ContributionDay, type Course, type CvDocument, type CvHeader, type CvSection, type CvSectionKind, DARK_PALETTE, type Education, type ExportOptions, type ExportedTakuhon, type GravatarOptions, type Honor, IMAGE_EXTENSIONS, type ImageInfo, ImportError, type Iso3166Alpha2, type IsoDateTime, LIGHT_PALETTE, type Language, type LanguageBreakdown, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedRecommendation, type LocalizedRecommendationAuthor, type LocalizedTakuhon, type LocalizedTestScore, type LocalizedTitle, type LocalizedVolunteering, MAX_IMAGE_BYTES, MAX_IMAGE_DIMENSION, MAX_IMAGE_FRAMES, MCP_PROFILE_SECTIONS, MCP_RESOURCES, MCP_TOOLS, type McpInputSchema, type McpProfileSection, McpRequestError, type McpResourceDefinition, type McpResourceResult, type McpToolDefinition, type McpToolResult, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Palette, type Patent, type PatentStatus, type Profile, type Project, type PublicVisibility, type Publication, RANK_FULL_CODING_HOURS, RANK_FULL_CONTRIBUTIONS, RANK_TIER_THRESHOLDS, type RankInput, type RankTier, type RankTierLabel, type Recommendation, type RecommendationAuthor, type RenderActivitySvgOptions, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type TestScore, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, applyPublicPrivacyFilter, computeLanguagePercentages, deriveCv, deriveRankTier, detectImageMime, executeMcpTool, exportTakuhon, formatCodingTime, formatDate, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, getPresentLabel, gravatarUrl, importTakuhon, isActivitySnapshot, migrateTakuhon, migrations, normalize, readImageInfo, readMcpResource, renderActivitySvg, resolveLocale, schema, stripImageMetadata, validate };