@ankhorage/contracts 7.0.0 → 7.2.0

package/src/appManifest/screens.ts

@@ -0,0 +1,171 @@
+import { COLOR_HARMONIES } from '@ankhorage/color-theory';
+
+import { APP_CATEGORIES, NAVIGATOR_TYPES } from '../types';
+import { isBindingValueSource, isScreenDataLoaderDefinition } from './bindings';
+import {
+  isOptionalBoolean,
+  isOptionalNumber,
+  isOptionalString,
+  isRecord,
+  isStringArray,
+} from './shared';
+
+const APP_CATEGORY_SET = new Set<string>(APP_CATEGORIES);
+const COLOR_HARMONY_SET = new Set<string>(COLOR_HARMONIES);
+const NAVIGATOR_TYPE_SET = new Set<string>(NAVIGATOR_TYPES);
+const SPLASH_SCREEN_RESIZE_MODE_SET = new Set<string>(['contain', 'cover', 'native']);
+
+export function isManifestMetadata(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    typeof value.slug === 'string' &&
+    typeof value.version === 'string' &&
+    typeof value.category === 'string' &&
+    APP_CATEGORY_SET.has(value.category) &&
+    typeof value.themeId === 'string' &&
+    isOptionalString(value.created) &&
+    isOptionalString(value.updated)
+  );
+}
+
+export function isThemeConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    isThemeModeConfig(value.light) &&
+    isThemeModeConfig(value.dark)
+  );
+}
+
+export function isNavigatorSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.type === 'string' &&
+    NAVIGATOR_TYPE_SET.has(value.type) &&
+    isOptionalString(value.initialRouteName) &&
+    Array.isArray(value.routes) &&
+    value.routes.every(isRouteDefinition) &&
+    (value.options === undefined || isRecord(value.options))
+  );
+}
+
+export function isScreenRegistry(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([registryKey, screen]) =>
+        isScreenSpec(screen) && isRecord(screen) && registryKey === screen.id,
+    )
+  );
+}
+
+export function isSplashScreenSpec(value: unknown): boolean {
+  return (
+    isSplashScreenModeSpec(value) &&
+    isRecord(value) &&
+    (value.dark === undefined || isSplashScreenModeSpec(value.dark))
+  );
+}
+
+function isThemeModeConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.primaryColor === 'string' &&
+    typeof value.harmony === 'string' &&
+    COLOR_HARMONY_SET.has(value.harmony)
+  );
+}
+
+function isUiNode(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.type === 'string' &&
+    isOptionalString(value.alias) &&
+    (value.props === undefined || isRecord(value.props)) &&
+    (value.style === undefined || isRecord(value.style)) &&
+    (value.repeat === undefined || isUiNodeRepeatSpec(value.repeat)) &&
+    (value.children === undefined ||
+      (Array.isArray(value.children) && value.children.every(isUiNode)))
+  );
+}
+
+function isUiNodeRepeatSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isBindingValueSource(value.source) &&
+    isOptionalString(value.itemAlias) &&
+    isOptionalString(value.keyPath) &&
+    (value.empty === undefined || (Array.isArray(value.empty) && value.empty.every(isUiNode)))
+  );
+}
+
+function isScreenSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.title) &&
+    isOptionalString(value.description) &&
+    (value.dataLoaders === undefined ||
+      (Array.isArray(value.dataLoaders) &&
+        value.dataLoaders.every(isScreenDataLoaderDefinition))) &&
+    (value.requires === undefined || isScreenRequirements(value.requires)) &&
+    isUiNode(value.root)
+  );
+}
+
+function isRouteDefinition(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.path) &&
+    isOptionalString(value.label) &&
+    (value.icon === undefined || isIconSpec(value.icon)) &&
+    isOptionalBoolean(value.showInPrimaryNavigation) &&
+    (value.guards === undefined || isStringArray(value.guards)) &&
+    isOptionalString(value.screenId) &&
+    (value.navigator === undefined || isNavigatorSpec(value.navigator))
+  );
+}
+
+function isIconSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.provider) &&
+    (value.size === undefined ||
+      typeof value.size === 'string' ||
+      typeof value.size === 'number') &&
+    isOptionalString(value.color)
+  );
+}
+
+function isSplashScreenModeSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isOptionalString(value.image) &&
+    isOptionalNumber(value.imageWidth) &&
+    (value.resizeMode === undefined ||
+      (typeof value.resizeMode === 'string' &&
+        SPLASH_SCREEN_RESIZE_MODE_SET.has(value.resizeMode))) &&
+    isOptionalString(value.backgroundColor)
+  );
+}
+
+function isScreenRequirements(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    (value.permissions === undefined || isRequirementArray(value.permissions, 'permission')) &&
+    (value.capabilities === undefined || isRequirementArray(value.capabilities, 'capability'))
+  );
+}
+
+function isRequirementArray(value: unknown, key: 'capability' | 'permission'): boolean {
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => isRecord(entry) && typeof entry[key] === 'string')
+  );
+}

package/src/appManifest/shared.ts

@@ -0,0 +1,40 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === 'string';
+}
+
+export function isOptionalNumber(value: unknown): boolean {
+  return value === undefined || typeof value === 'number';
+}
+
+export function isOptionalBoolean(value: unknown): boolean {
+  return value === undefined || typeof value === 'boolean';
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+export function isStringRecord(value: unknown): boolean {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string');
+}
+
+export function isManifestValue(value: unknown): boolean {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isManifestValue);
+  }
+
+  return isRecord(value) && Object.values(value).every(isManifestValue);
+}

package/src/appManifest.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isAppManifest, parseAppManifest } from './appManifest';
+
+function createManifest(): Record<string, unknown> {
+  return {
+    metadata: {
+      name: 'Example',
+      slug: 'example',
+      version: '1.0.0',
+      category: 'developer_tools',
+      themeId: 'default',
+    },
+    themes: [
+      {
+        id: 'default',
+        name: 'Default',
+        light: { primaryColor: '#3366ff', harmony: 'analogous' },
+        dark: { primaryColor: '#6699ff', harmony: 'analogous' },
+      },
+    ],
+    activeThemeId: 'default',
+    activeThemeMode: 'light',
+    splashScreen: {
+      image: './assets/splash.png',
+      resizeMode: 'contain',
+      backgroundColor: '#ffffff',
+      dark: { backgroundColor: '#000000' },
+    },
+    infra: {
+      deployment: { target: 'minikube', monitoring: true },
+      database: { provider: 'supabase', tier: 'dev' },
+      storage: { provider: 'auto', buckets: ['media'] },
+      state: { provider: 'legend', persistence: 'local' },
+      networking: { domain: 'example.test', cdn: false },
+      modules: ['expo-localization'],
+      modulesConfig: { localization: { defaultLocale: 'en' } },
+    },
+    navigator: {
+      type: 'stack',
+      initialRouteName: 'home',
+      routes: [
+        {
+          name: 'home',
+          path: '/',
+          screenId: 'home',
+          showInPrimaryNavigation: true,
+        },
+      ],
+    },
+    screens: {
+      home: {
+        id: 'home',
+        name: 'Home',
+        root: {
+          id: 'root',
+          type: 'Stack',
+          children: [
+            {
+              id: 'title',
+              type: 'Text',
+              repeat: { source: { kind: 'state', path: 'items' }, itemAlias: 'item' },
+            },
+          ],
+        },
+        dataLoaders: [
+          {
+            kind: 'operation',
+            id: 'load-users',
+            operation: { dataSourceId: 'external', endpointId: 'main', operationId: 'list' },
+          },
+        ],
+        requires: {
+          permissions: [{ permission: 'camera' }],
+          capabilities: [{ capability: 'barcodeScanner' }],
+        },
+      },
+    },
+    generatedApis: {
+      users: {
+        id: 'users',
+        protocol: 'rest',
+        basePath: '/users',
+        database: { id: 'primary', kind: 'database' },
+        resources: [
+          {
+            id: 'users',
+            path: '/users',
+            collection: {
+              name: 'users',
+              fields: [{ name: 'id', type: 'uuid', required: true }],
+              primaryKey: 'id',
+            },
+            operations: ['list', 'read'],
+          },
+        ],
+      },
+    },
+    dataSources: {
+      external: {
+        id: 'external',
+        kind: 'api',
+        origin: 'external',
+        protocol: 'rest',
+        baseUrl: 'https://example.test',
+        endpoints: {
+          main: {
+            id: 'main',
+            kind: 'http',
+            operations: {
+              list: { id: 'list', protocol: 'rest', intent: 'read', path: '/users' },
+            },
+          },
+        },
+      },
+    },
+    dataBindings: {
+      title: {
+        componentId: 'title',
+        props: { text: { source: { kind: 'state', path: 'title' } } },
+        events: {
+          press: [{ target: { kind: 'action', type: 'console' } }],
+        },
+      },
+    },
+    settings: {
+      apiBaseUrl: 'https://example.test/api',
+      localization: { defaultLocale: 'en', locales: ['en', 'de'] },
+    },
+  };
+}
+
+describe('AppManifest runtime parsing', () => {
+  it('accepts the canonical manifest including optional nested sections', () => {
+    const manifest = createManifest();
+
+    expect(isAppManifest(manifest)).toBe(true);
+    expect(parseAppManifest(manifest)).toEqual({ ok: true, manifest });
+  });
+
+  it('rejects missing required top-level sections', () => {
+    const manifest = createManifest();
+    delete manifest.settings;
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects malformed nested canonical structures', () => {
+    const manifest = createManifest();
+    const themes = manifest.themes as Record<string, unknown>[];
+    const light = themes[0]?.light as Record<string, unknown>;
+    light.harmony = 'not-a-harmony';
+
+    expect(parseAppManifest(manifest)).toEqual({
+      ok: false,
+      message: 'Value is not a canonical AppManifest.',
+    });
+  });
+
+  it('rejects legacy infra plugin state', () => {
+    const manifest = createManifest();
+    const infra = manifest.infra as Record<string, unknown>;
+    infra.plugins = ['legacy'];
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects screen registries whose key disagrees with screen id', () => {
+    const manifest = createManifest();
+    const screens = manifest.screens as Record<string, unknown>;
+    screens.other = screens.home;
+    delete screens.home;
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+
+  it('rejects invalid data-binding source kinds', () => {
+    const manifest = createManifest();
+    const bindings = manifest.dataBindings as Record<string, Record<string, unknown>>;
+    const props = bindings.title?.props as Record<string, Record<string, unknown>>;
+    props.text = { source: { kind: 'provider-specific', path: 'title' } };
+
+    expect(isAppManifest(manifest)).toBe(false);
+  });
+});

package/src/appManifest.ts

@@ -0,0 +1,86 @@
+import { isComponentDataBindingRegistry } from './appManifest/bindings';
+import { isDataSourceRegistry } from './appManifest/dataSources';
+import { isGeneratedApiRegistry } from './appManifest/generatedApis';
+import { isInfraManifest } from './appManifest/infra';
+import {
+  isManifestMetadata,
+  isNavigatorSpec,
+  isScreenRegistry,
+  isSplashScreenSpec,
+  isThemeConfig,
+} from './appManifest/screens';
+import { isOptionalString, isRecord, isStringArray } from './appManifest/shared';
+import type { AppManifest } from './types';
+
+export type AppManifestParseResult =
+  | { readonly ok: true; readonly manifest: AppManifest }
+  | { readonly ok: false; readonly message: string };
+
+const APP_MANIFEST_KEY_POLICY = {
+  metadata: 'required',
+  themes: 'required',
+  activeThemeId: 'required',
+  activeThemeMode: 'optional',
+  splashScreen: 'optional',
+  infra: 'required',
+  navigator: 'required',
+  screens: 'required',
+  generatedApis: 'optional',
+  dataSources: 'optional',
+  dataBindings: 'optional',
+  settings: 'required',
+} as const satisfies Record<keyof AppManifest, 'optional' | 'required'>;
+
+/**
+ * Parse unknown JSON-compatible input at the canonical AppManifest boundary.
+ *
+ * Contracts owns structural manifest validation. Consumers may add semantic
+ * diagnostics after this parser succeeds, but should not reconstruct the
+ * AppManifest shape in their own packages.
+ */
+export function parseAppManifest(value: unknown): AppManifestParseResult {
+  return isAppManifest(value)
+    ? { ok: true, manifest: value }
+    : { ok: false, message: 'Value is not a canonical AppManifest.' };
+}
+
+/** Return whether an unknown value satisfies the canonical AppManifest shape. */
+export function isAppManifest(value: unknown): value is AppManifest {
+  return (
+    isRecord(value) &&
+    hasRequiredManifestKeys(value) &&
+    isManifestMetadata(value.metadata) &&
+    Array.isArray(value.themes) &&
+    value.themes.every(isThemeConfig) &&
+    typeof value.activeThemeId === 'string' &&
+    isActiveThemeMode(value.activeThemeMode) &&
+    (value.splashScreen === undefined || isSplashScreenSpec(value.splashScreen)) &&
+    isInfraManifest(value.infra) &&
+    isNavigatorSpec(value.navigator) &&
+    isScreenRegistry(value.screens) &&
+    (value.generatedApis === undefined || isGeneratedApiRegistry(value.generatedApis)) &&
+    (value.dataSources === undefined || isDataSourceRegistry(value.dataSources)) &&
+    (value.dataBindings === undefined || isComponentDataBindingRegistry(value.dataBindings)) &&
+    isAppSettings(value.settings)
+  );
+}
+
+function hasRequiredManifestKeys(value: Record<string, unknown>): boolean {
+  return Object.entries(APP_MANIFEST_KEY_POLICY).every(
+    ([key, policy]) => policy === 'optional' || key in value,
+  );
+}
+
+function isActiveThemeMode(value: unknown): boolean {
+  return value === undefined || value === 'dark' || value === 'light';
+}
+
+function isAppSettings(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isRecord(value.localization) &&
+    typeof value.localization.defaultLocale === 'string' &&
+    isStringArray(value.localization.locales) &&
+    isOptionalString(value.apiBaseUrl)
+  );
+}

package/src/contracts.test.ts

@@ -156,6 +156,46 @@ describe('contracts', () => {
     expect(theme.light.harmony).toBe('analogous');
   });
 
+  it('serializes authored global theme tokens and recipe override values', () => {
+    const theme: ThemeConfig = {
+      id: 'theme-default',
+      name: 'Default',
+      light: {
+        primaryColor: '#3366ff',
+        harmony: 'analogous',
+      },
+      dark: {
+        primaryColor: '#7799ff',
+        harmony: 'analogous',
+      },
+      tokens: {
+        spacing: { m: 18, l: 28 },
+        radii: { m: 10, l: 18 },
+        typography: {
+          sizes: { body: 16, lead: 20 },
+          weights: { body: '400', strong: '700' },
+          headings: {
+            h1: { size: 34, lineHeight: 42, weight: '700' },
+          },
+        },
+        shadows: { soft: 3 },
+      },
+      recipes: {
+        components: {
+          Card: { compact: true, padding: 'l', radius: 'm', tone: 'subtle' },
+        },
+        patterns: {
+          Panel: { compact: false, padding: 'xl' },
+        },
+      },
+    };
+
+    expect(JSON.parse(JSON.stringify(theme))).toEqual(theme);
+    expect(theme.tokens?.spacing?.m).toBe(18);
+    expect(theme.recipes?.components?.Card?.compact).toBe(true);
+    expect(theme.recipes?.patterns?.Panel?.padding).toBe('xl');
+  });
+
   it('accepts serializable splash screen branding on app manifests', () => {
     const splashScreen: SplashScreenSpec = {
       backgroundColor: '#ffffff',

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './appManifest';
 export * from './auth';
 export * from './bindings';
 export * from './cli';
@@ -9,5 +10,6 @@ export * from './secretManifest';
 export * from './secrets';
 export * from './state';
 export * from './storage';
+export * from './theme';
 export * from './types';
 export * from './ui';

package/src/theme.ts

@@ -0,0 +1,50 @@
+/** Numeric token values authored at theme level. */
+export type ThemeNumericTokenOverrides = Readonly<Record<string, number>>;
+
+/** String token values authored at theme level. */
+export type ThemeStringTokenOverrides = Readonly<Record<string, string>>;
+
+/** Partial authored override for one semantic heading recipe. */
+export interface ThemeTypographyHeadingOverrides {
+  readonly size?: number;
+  readonly lineHeight?: number;
+  readonly weight?: string;
+}
+
+/** Theme-global typography source overrides. Font installation remains module-owned. */
+export interface ThemeTypographyTokenOverrides {
+  readonly headings?: Readonly<Record<string, ThemeTypographyHeadingOverrides>>;
+  readonly sizes?: ThemeNumericTokenOverrides;
+  readonly weights?: ThemeStringTokenOverrides;
+}
+
+/**
+ * Theme-global authored token overrides.
+ *
+ * Color source remains mode-specific on ThemeModeConfig. These values are shared by
+ * light and dark mode and are resolved by the render-theme owner rather than copied
+ * into every mode branch.
+ */
+export interface ThemeGlobalTokenOverrides {
+  readonly spacing?: ThemeNumericTokenOverrides;
+  readonly radii?: ThemeNumericTokenOverrides;
+  readonly typography?: ThemeTypographyTokenOverrides;
+  readonly shadows?: ThemeNumericTokenOverrides;
+}
+
+/** Serializable value supported by the current theme-recipe metadata field kinds. */
+export type ThemeRecipeOverrideValue = boolean | string;
+
+/** Persisted values for one component or pattern recipe. */
+export type ThemeRecipeFieldOverrides = Readonly<Record<string, ThemeRecipeOverrideValue>>;
+
+/**
+ * Generic persisted recipe values.
+ *
+ * The owning UI package defines available recipes, field schemas, defaults and token
+ * relationships. Contracts stores selected values only and does not duplicate that metadata.
+ */
+export interface ThemeRecipeOverrides {
+  readonly components?: Readonly<Record<string, ThemeRecipeFieldOverrides>>;
+  readonly patterns?: Readonly<Record<string, ThemeRecipeFieldOverrides>>;
+}

package/src/types.ts

@@ -8,6 +8,7 @@ import type {
 } from './bindings';
 import type { DataSourceRegistry, GeneratedApiRegistry } from './data';
 import type { ScreenRequirements } from './requirements';
+import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme';
 
 export interface ThemeModeConfig {
   primaryColor: string;
@@ -19,6 +20,10 @@ export interface ThemeConfig {
   name: string;
   light: ThemeModeConfig;
   dark: ThemeModeConfig;
+  /** Theme-global authored token overrides shared by light and dark mode. */
+  tokens?: ThemeGlobalTokenOverrides;
+  /** Component/pattern recipe override values; recipe schemas remain package-owned metadata. */
+  recipes?: ThemeRecipeOverrides;
 }
 
 export type ActionType =