@hanzo/mod 0.0.0-stage → 0.1.0

package/dist/font.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dynamic custom font loader and manager for organizations and designers.
+ */
+export interface CustomFontOptions {
+    family: string;
+    url: string;
+    format?: 'woff2' | 'woff' | 'truetype' | 'opentype';
+    weights?: (number | string)[];
+    isStylesheet?: boolean;
+}
+/**
+ * Injects a designer/organization custom font into document head dynamically.
+ * Supports direct webfont stylesheets (Google Fonts, Adobe Fonts, Typekit) or @font-face binaries.
+ */
+export declare function injectCustomFont(options: CustomFontOptions): void;
+/** Removes an injected custom font stylesheet or style tag */
+export declare function removeCustomFont(family: string): void;
+/** Statically applies a font-family to CSS variables */
+export declare function applyFontFamily(target: 'heading' | 'sans' | 'mono', fontFamily: string): void;

package/dist/font.js

@@ -0,0 +1,59 @@
+/**
+ * Dynamic custom font loader and manager for organizations and designers.
+ */
+const INJECTED_FONT_PREFIX = 'hanzo-font-';
+/**
+ * Injects a designer/organization custom font into document head dynamically.
+ * Supports direct webfont stylesheets (Google Fonts, Adobe Fonts, Typekit) or @font-face binaries.
+ */
+export function injectCustomFont(options) {
+    if (typeof document === 'undefined')
+        return;
+    const elementId = `${INJECTED_FONT_PREFIX}${options.family.toLowerCase().replace(/[^a-z0-9]/g, '-')}`;
+    const existing = document.getElementById(elementId);
+    if (existing)
+        existing.remove();
+    if (options.isStylesheet || options.url.endsWith('.css') || options.url.includes('fonts.googleapis.com')) {
+        const link = document.createElement('link');
+        link.id = elementId;
+        link.rel = 'stylesheet';
+        link.href = options.url;
+        document.head.appendChild(link);
+    }
+    else {
+        const format = options.format || (options.url.endsWith('.woff2') ? 'woff2' : options.url.endsWith('.woff') ? 'woff' : 'truetype');
+        const weights = options.weights || [400, 500, 600, 700];
+        let fontFaceRules = '';
+        for (const w of weights) {
+            fontFaceRules += `
+        @font-face {
+          font-family: "${options.family}";
+          src: url("${options.url}") format("${format}");
+          font-weight: ${w};
+          font-style: normal;
+          font-display: swap;
+        }
+      `;
+        }
+        const style = document.createElement('style');
+        style.id = elementId;
+        style.textContent = fontFaceRules;
+        document.head.appendChild(style);
+    }
+}
+/** Removes an injected custom font stylesheet or style tag */
+export function removeCustomFont(family) {
+    if (typeof document === 'undefined')
+        return;
+    const elementId = `${INJECTED_FONT_PREFIX}${family.toLowerCase().replace(/[^a-z0-9]/g, '-')}`;
+    const el = document.getElementById(elementId);
+    if (el)
+        el.remove();
+}
+/** Statically applies a font-family to CSS variables */
+export function applyFontFamily(target, fontFamily) {
+    if (typeof document === 'undefined')
+        return;
+    const cssVar = target === 'heading' ? '--font-heading' : target === 'mono' ? '--font-mono' : '--font-sans';
+    document.documentElement.style.setProperty(cssVar, fontFamily);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { detectPlatform, getActivePlatform, setActivePlatform, applyPlatformTokens, PLATFORM_PROFILES, type PlatformId, type PlatformProfile, } from './platform.js';
+export { exportMod, importMod, forkMod, applyMod, saveOrgMod, getOrgMod, BUILTIN_MODS, type ModTheme, } from './theme.js';
+export { injectCustomFont, removeCustomFont, applyFontFamily, type CustomFontOptions, } from './font.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { detectPlatform, getActivePlatform, setActivePlatform, applyPlatformTokens, PLATFORM_PROFILES, } from './platform.js';
+export { exportMod, importMod, forkMod, applyMod, saveOrgMod, getOrgMod, BUILTIN_MODS, } from './theme.js';
+export { injectCustomFont, removeCustomFont, applyFontFamily, } from './font.js';

package/dist/platform.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Native OS platform detection and design system adaptors for Hanzo.
+ *
+ * Configures native look/feel tailored to the user's OS:
+ * - iOS: Continuous squircles, Liquid Glass blurs, SF Pro fonts, safe area insets, specular highlights
+ * - Android: Material 3 tokens, Roboto/Google Sans, tonal elevations, ripple curves
+ * - macOS: Vibrant translucent glass, compact desktop paddings
+ * - Windows: Fluent/Mica acrylic glass, sharp modern geometry
+ * - Linux: Clean system lines, flat modern edges
+ */
+export type PlatformId = 'ios' | 'android' | 'macos' | 'windows' | 'linux';
+export interface PlatformProfile {
+    id: PlatformId;
+    name: string;
+    fontFamily: string;
+    fontMono: string;
+    radiusCard: number | string;
+    radiusPill: number | string;
+    glassBlur: number;
+    glassSaturate: number;
+    specularBorder: boolean;
+    touchFeedback: 'spring' | 'ripple' | 'subtle';
+}
+export declare const PLATFORM_PROFILES: Record<PlatformId, PlatformProfile>;
+/** Detects the current OS platform from user agent strings */
+export declare function detectPlatform(userAgent?: string): PlatformId;
+/** Reads the user's active platform preference (stored or detected) */
+export declare function getActivePlatform(): PlatformId;
+/** Sets the user's preferred platform customization */
+export declare function setActivePlatform(platform: PlatformId | 'auto'): void;
+/** Statically stamps the platform CSS custom properties onto documentElement */
+export declare function applyPlatformTokens(platform: PlatformId): void;

package/dist/platform.js

@@ -0,0 +1,135 @@
+/**
+ * Native OS platform detection and design system adaptors for Hanzo.
+ *
+ * Configures native look/feel tailored to the user's OS:
+ * - iOS: Continuous squircles, Liquid Glass blurs, SF Pro fonts, safe area insets, specular highlights
+ * - Android: Material 3 tokens, Roboto/Google Sans, tonal elevations, ripple curves
+ * - macOS: Vibrant translucent glass, compact desktop paddings
+ * - Windows: Fluent/Mica acrylic glass, sharp modern geometry
+ * - Linux: Clean system lines, flat modern edges
+ */
+export const PLATFORM_PROFILES = {
+    ios: {
+        id: 'ios',
+        name: 'Apple iOS',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", "SF Pro Display", sans-serif',
+        fontMono: '"SF Mono", ui-monospace, Menlo, monospace',
+        radiusCard: 22,
+        radiusPill: 9999,
+        glassBlur: 24,
+        glassSaturate: 190,
+        specularBorder: true,
+        touchFeedback: 'spring',
+    },
+    android: {
+        id: 'android',
+        name: 'Google Android',
+        fontFamily: 'Roboto, "Google Sans", system-ui, sans-serif',
+        fontMono: '"Roboto Mono", monospace',
+        radiusCard: 16,
+        radiusPill: 16,
+        glassBlur: 16,
+        glassSaturate: 130,
+        specularBorder: false,
+        touchFeedback: 'ripple',
+    },
+    macos: {
+        id: 'macos',
+        name: 'Apple macOS',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif',
+        fontMono: '"SF Mono", Menlo, monospace',
+        radiusCard: 12,
+        radiusPill: 9999,
+        glassBlur: 20,
+        glassSaturate: 160,
+        specularBorder: true,
+        touchFeedback: 'subtle',
+    },
+    windows: {
+        id: 'windows',
+        name: 'Microsoft Windows',
+        fontFamily: '"Segoe UI Variable", "Segoe UI", system-ui, sans-serif',
+        fontMono: '"Cascadia Code", Consolas, monospace',
+        radiusCard: 8,
+        radiusPill: 9999,
+        glassBlur: 18,
+        glassSaturate: 125,
+        specularBorder: false,
+        touchFeedback: 'subtle',
+    },
+    linux: {
+        id: 'linux',
+        name: 'Linux / Desktop',
+        fontFamily: 'system-ui, -apple-system, "Cantarell", sans-serif',
+        fontMono: '"Ubuntu Mono", monospace',
+        radiusCard: 10,
+        radiusPill: 9999,
+        glassBlur: 14,
+        glassSaturate: 110,
+        specularBorder: false,
+        touchFeedback: 'subtle',
+    },
+};
+const STORAGE_KEY = 'hanzo.mod.platform';
+/** Detects the current OS platform from user agent strings */
+export function detectPlatform(userAgent) {
+    const ua = (userAgent ?? (typeof navigator !== 'undefined' ? navigator.userAgent : '')).toLowerCase();
+    if (/iphone|ipad|ipod/.test(ua) || (typeof navigator !== 'undefined' && navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1)) {
+        return 'ios';
+    }
+    if (/android/.test(ua))
+        return 'android';
+    if (/macintosh|mac os x/.test(ua))
+        return 'macos';
+    if (/windows|win32|win64/.test(ua))
+        return 'windows';
+    if (/linux|x11/.test(ua))
+        return 'linux';
+    return 'ios';
+}
+/** Reads the user's active platform preference (stored or detected) */
+export function getActivePlatform() {
+    if (typeof window === 'undefined')
+        return 'ios';
+    try {
+        const kept = window.localStorage.getItem(STORAGE_KEY);
+        if (kept && kept in PLATFORM_PROFILES)
+            return kept;
+    }
+    catch {
+        // ignore storage restrictions
+    }
+    return detectPlatform();
+}
+/** Sets the user's preferred platform customization */
+export function setActivePlatform(platform) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        if (platform === 'auto') {
+            window.localStorage.removeItem(STORAGE_KEY);
+        }
+        else {
+            window.localStorage.setItem(STORAGE_KEY, platform);
+        }
+    }
+    catch {
+        // ignore storage restrictions
+    }
+    applyPlatformTokens(platform === 'auto' ? detectPlatform() : platform);
+    window.dispatchEvent(new CustomEvent('hanzo:mod:change', { detail: { platform } }));
+}
+/** Statically stamps the platform CSS custom properties onto documentElement */
+export function applyPlatformTokens(platform) {
+    if (typeof document === 'undefined')
+        return;
+    const profile = PLATFORM_PROFILES[platform] ?? PLATFORM_PROFILES.ios;
+    const root = document.documentElement;
+    root.setAttribute('data-platform', profile.id);
+    root.style.setProperty('--platform-font-sans', profile.fontFamily);
+    root.style.setProperty('--platform-font-mono', profile.fontMono);
+    root.style.setProperty('--platform-radius-card', typeof profile.radiusCard === 'number' ? `${profile.radiusCard}px` : profile.radiusCard);
+    root.style.setProperty('--platform-radius-pill', typeof profile.radiusPill === 'number' ? `${profile.radiusPill}px` : profile.radiusPill);
+    root.style.setProperty('--glass-blur', `${profile.glassBlur}px`);
+    root.style.setProperty('--glass-saturate', `${profile.glassSaturate}%`);
+}

package/dist/theme.d.ts

@@ -0,0 +1,33 @@
+import { type PlatformId } from './platform.js';
+export interface ModTheme {
+    id: string;
+    name: string;
+    description?: string;
+    author?: string;
+    org?: string;
+    platform?: PlatformId;
+    fontHeading?: string;
+    fontBody?: string;
+    fontMono?: string;
+    customFontUrl?: string;
+    primary?: string;
+    accent?: string;
+    glassTint?: string;
+    glassBlur?: number;
+    radius?: number;
+    density?: 'compact' | 'comfortable' | 'default';
+    customCss?: string;
+}
+export declare const BUILTIN_MODS: ModTheme[];
+/** Serializes a theme mod to JSON for exporting/sharing */
+export declare function exportMod(mod: ModTheme): string;
+/** Parses and validates an imported mod JSON string */
+export declare function importMod(json: string): ModTheme;
+/** Creates a new mod derived from an existing base theme */
+export declare function forkMod(base: ModTheme, overrides: Partial<ModTheme>): ModTheme;
+/** Applies a theme mod dynamically to the page */
+export declare function applyMod(mod: ModTheme): void;
+/** Saves an organization-scoped mod configuration */
+export declare function saveOrgMod(orgId: string, mod: ModTheme): void;
+/** Gets the active mod for an organization */
+export declare function getOrgMod(orgId: string): ModTheme | null;

package/dist/theme.js

@@ -0,0 +1,176 @@
+import { PLATFORM_PROFILES, applyPlatformTokens } from './platform.js';
+export const BUILTIN_MODS = [
+    {
+        id: 'ios-liquid',
+        name: 'Apple iOS Liquid',
+        description: 'Continuous squircles, high-specular liquid glass, and Apple SF Pro typography.',
+        author: 'Hanzo Design',
+        platform: 'ios',
+        glassBlur: 24,
+        radius: 22,
+        density: 'comfortable',
+    },
+    {
+        id: 'android-material',
+        name: 'Android Material 3',
+        description: 'Google Material 3 tonal elevations, Roboto Sans, and smooth dynamic rounded cards.',
+        author: 'Hanzo Design',
+        platform: 'android',
+        glassBlur: 16,
+        radius: 16,
+        density: 'default',
+    },
+    {
+        id: 'macos-vibrant',
+        name: 'macOS Vibrant',
+        description: 'Translucent sidebars, vibrant visual effect filters, and clean desktop density.',
+        author: 'Hanzo Design',
+        platform: 'macos',
+        glassBlur: 20,
+        radius: 12,
+        density: 'compact',
+    },
+    {
+        id: 'windows-fluent',
+        name: 'Windows Mica Fluent',
+        description: 'Microsoft Fluent Design Mica acrylic and Segoe UI Variable geometry.',
+        author: 'Hanzo Design',
+        platform: 'windows',
+        glassBlur: 18,
+        radius: 8,
+        density: 'default',
+    },
+    {
+        id: 'cyber-zen',
+        name: 'Cyber Zen (OLED)',
+        description: 'High contrast deep OLED black with electric cyan and magenta accents.',
+        author: 'Hanzo Labs',
+        platform: 'ios',
+        primary: '#00f0ff',
+        accent: '#ff007f',
+        glassBlur: 28,
+        radius: 20,
+        density: 'comfortable',
+    },
+    {
+        id: 'nordic-frost',
+        name: 'Nordic Frost',
+        description: 'Pure arctic monochrome glass, high clarity, and minimalist typography.',
+        author: 'Hanzo Design',
+        platform: 'macos',
+        primary: '#e2e8f0',
+        accent: '#38bdf8',
+        glassBlur: 22,
+        radius: 14,
+        density: 'default',
+    },
+];
+const ORG_MOD_KEY = (orgId) => `hanzo.mod.org.${orgId}`;
+const ACTIVE_MOD_KEY = 'hanzo.mod.active';
+/** Serializes a theme mod to JSON for exporting/sharing */
+export function exportMod(mod) {
+    return JSON.stringify(mod, null, 2);
+}
+/** Parses and validates an imported mod JSON string */
+export function importMod(json) {
+    const parsed = JSON.parse(json);
+    if (!parsed || typeof parsed !== 'object' || !parsed.name) {
+        throw new Error('Invalid Hanzo mod: missing theme name');
+    }
+    return {
+        id: parsed.id || `mod-${Date.now()}`,
+        name: String(parsed.name).slice(0, 64),
+        description: parsed.description ? String(parsed.description).slice(0, 256) : undefined,
+        author: parsed.author ? String(parsed.author).slice(0, 64) : undefined,
+        org: parsed.org,
+        platform: parsed.platform && parsed.platform in PLATFORM_PROFILES ? parsed.platform : undefined,
+        fontHeading: parsed.fontHeading,
+        fontBody: parsed.fontBody,
+        fontMono: parsed.fontMono,
+        customFontUrl: parsed.customFontUrl,
+        primary: parsed.primary,
+        accent: parsed.accent,
+        glassTint: parsed.glassTint,
+        glassBlur: typeof parsed.glassBlur === 'number' ? parsed.glassBlur : undefined,
+        radius: typeof parsed.radius === 'number' ? parsed.radius : undefined,
+        density: parsed.density,
+        customCss: parsed.customCss,
+    };
+}
+/** Creates a new mod derived from an existing base theme */
+export function forkMod(base, overrides) {
+    return {
+        ...base,
+        ...overrides,
+        id: overrides.id || `${base.id}-fork-${Date.now().toString(36)}`,
+        name: overrides.name || `${base.name} (Mod)`,
+    };
+}
+/** Applies a theme mod dynamically to the page */
+export function applyMod(mod) {
+    if (typeof document === 'undefined')
+        return;
+    const root = document.documentElement;
+    if (mod.platform) {
+        applyPlatformTokens(mod.platform);
+    }
+    if (mod.primary)
+        root.style.setProperty('--primary', mod.primary);
+    if (mod.accent)
+        root.style.setProperty('--accent', mod.accent);
+    if (mod.glassTint)
+        root.style.setProperty('--liquid-glass-bg', mod.glassTint);
+    if (typeof mod.glassBlur === 'number')
+        root.style.setProperty('--glass-blur', `${mod.glassBlur}px`);
+    if (typeof mod.radius === 'number')
+        root.style.setProperty('--radius', `${mod.radius}px`);
+    if (mod.fontHeading)
+        root.style.setProperty('--font-heading', mod.fontHeading);
+    if (mod.fontBody)
+        root.style.setProperty('--font-body', mod.fontBody);
+    if (mod.fontMono)
+        root.style.setProperty('--font-mono', mod.fontMono);
+    // Inject custom CSS if defined
+    let styleEl = document.getElementById('hanzo-custom-mod-css');
+    if (mod.customCss) {
+        if (!styleEl) {
+            styleEl = document.createElement('style');
+            styleEl.id = 'hanzo-custom-mod-css';
+            document.head.appendChild(styleEl);
+        }
+        styleEl.textContent = mod.customCss;
+    }
+    else if (styleEl) {
+        styleEl.remove();
+    }
+    try {
+        window.localStorage.setItem(ACTIVE_MOD_KEY, JSON.stringify(mod));
+        window.dispatchEvent(new CustomEvent('hanzo:mod:applied', { detail: { mod } }));
+    }
+    catch {
+        // ignore
+    }
+}
+/** Saves an organization-scoped mod configuration */
+export function saveOrgMod(orgId, mod) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(ORG_MOD_KEY(orgId), JSON.stringify({ ...mod, org: orgId }));
+    }
+    catch {
+        // ignore
+    }
+}
+/** Gets the active mod for an organization */
+export function getOrgMod(orgId) {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const raw = window.localStorage.getItem(ORG_MOD_KEY(orgId));
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@hanzo/mod",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Native OS look/feel customization, custom fonts, and mod themes for Hanzo.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "Apache-2.0 OR MIT",
+  "devDependencies": {
+    "@types/node": "26.5.0",
+    "@types/react": "19.2.18",
+    "react": "19.2.8",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../app/scripts/specifiers.mjs ./dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/font.ts

@@ -0,0 +1,69 @@
+/**
+ * Dynamic custom font loader and manager for organizations and designers.
+ */
+
+export interface CustomFontOptions {
+  family: string
+  url: string
+  format?: 'woff2' | 'woff' | 'truetype' | 'opentype'
+  weights?: (number | string)[]
+  isStylesheet?: boolean
+}
+
+const INJECTED_FONT_PREFIX = 'hanzo-font-'
+
+/**
+ * Injects a designer/organization custom font into document head dynamically.
+ * Supports direct webfont stylesheets (Google Fonts, Adobe Fonts, Typekit) or @font-face binaries.
+ */
+export function injectCustomFont(options: CustomFontOptions): void {
+  if (typeof document === 'undefined') return
+
+  const elementId = `${INJECTED_FONT_PREFIX}${options.family.toLowerCase().replace(/[^a-z0-9]/g, '-')}`
+  const existing = document.getElementById(elementId)
+  if (existing) existing.remove()
+
+  if (options.isStylesheet || options.url.endsWith('.css') || options.url.includes('fonts.googleapis.com')) {
+    const link = document.createElement('link')
+    link.id = elementId
+    link.rel = 'stylesheet'
+    link.href = options.url
+    document.head.appendChild(link)
+  } else {
+    const format = options.format || (options.url.endsWith('.woff2') ? 'woff2' : options.url.endsWith('.woff') ? 'woff' : 'truetype')
+    const weights = options.weights || [400, 500, 600, 700]
+
+    let fontFaceRules = ''
+    for (const w of weights) {
+      fontFaceRules += `
+        @font-face {
+          font-family: "${options.family}";
+          src: url("${options.url}") format("${format}");
+          font-weight: ${w};
+          font-style: normal;
+          font-display: swap;
+        }
+      `
+    }
+
+    const style = document.createElement('style')
+    style.id = elementId
+    style.textContent = fontFaceRules
+    document.head.appendChild(style)
+  }
+}
+
+/** Removes an injected custom font stylesheet or style tag */
+export function removeCustomFont(family: string): void {
+  if (typeof document === 'undefined') return
+  const elementId = `${INJECTED_FONT_PREFIX}${family.toLowerCase().replace(/[^a-z0-9]/g, '-')}`
+  const el = document.getElementById(elementId)
+  if (el) el.remove()
+}
+
+/** Statically applies a font-family to CSS variables */
+export function applyFontFamily(target: 'heading' | 'sans' | 'mono', fontFamily: string): void {
+  if (typeof document === 'undefined') return
+  const cssVar = target === 'heading' ? '--font-heading' : target === 'mono' ? '--font-mono' : '--font-sans'
+  document.documentElement.style.setProperty(cssVar, fontFamily)
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export {
+  detectPlatform,
+  getActivePlatform,
+  setActivePlatform,
+  applyPlatformTokens,
+  PLATFORM_PROFILES,
+  type PlatformId,
+  type PlatformProfile,
+} from './platform'
+
+export {
+  exportMod,
+  importMod,
+  forkMod,
+  applyMod,
+  saveOrgMod,
+  getOrgMod,
+  BUILTIN_MODS,
+  type ModTheme,
+} from './theme'
+
+export {
+  injectCustomFont,
+  removeCustomFont,
+  applyFontFamily,
+  type CustomFontOptions,
+} from './font'

package/src/mod.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { detectPlatform, PLATFORM_PROFILES } from './platform'
+import { BUILTIN_MODS, exportMod, forkMod, importMod } from './theme'
+
+describe('mod system', () => {
+  it('detects platforms accurately from user agents', () => {
+    expect(detectPlatform('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15')).toBe('ios')
+    expect(detectPlatform('Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36')).toBe('android')
+    expect(detectPlatform('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36')).toBe('macos')
+    expect(detectPlatform('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36')).toBe('windows')
+    expect(detectPlatform('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36')).toBe('linux')
+  })
+
+  it('provides platform profiles with correct typography and radius', () => {
+    expect(PLATFORM_PROFILES.ios.radiusCard).toBe(22)
+    expect(PLATFORM_PROFILES.ios.glassBlur).toBe(24)
+    expect(PLATFORM_PROFILES.android.radiusCard).toBe(16)
+    expect(PLATFORM_PROFILES.windows.radiusCard).toBe(8)
+  })
+
+  it('serializes and deserializes mods cleanly', () => {
+    const base = BUILTIN_MODS[0]
+    const json = exportMod(base)
+    const imported = importMod(json)
+    expect(imported.name).toBe(base.name)
+    expect(imported.platform).toBe(base.platform)
+  })
+
+  it('forks mods with custom designer overrides', () => {
+    const base = BUILTIN_MODS[0]
+    const forked = forkMod(base, {
+      name: 'Acme Brand Theme',
+      primary: '#10b981',
+      fontHeading: 'Cabinet Grotesk',
+    })
+    expect(forked.name).toBe('Acme Brand Theme')
+    expect(forked.primary).toBe('#10b981')
+    expect(forked.fontHeading).toBe('Cabinet Grotesk')
+    expect(forked.platform).toBe('ios')
+  })
+})

package/src/platform.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'vitest'
+import { PLATFORM_PROFILES, type PlatformId } from './platform'
+
+describe('@hanzo/mod platform profiles', () => {
+  test('defines profiles for all major platforms', () => {
+    const platforms: PlatformId[] = ['ios', 'android', 'macos', 'windows', 'linux']
+    for (const p of platforms) {
+      expect(PLATFORM_PROFILES[p]).toBeDefined()
+      expect(PLATFORM_PROFILES[p].id).toBe(p)
+      expect(PLATFORM_PROFILES[p].fontFamily).toBeDefined()
+    }
+  })
+})

package/src/platform.ts

@@ -0,0 +1,146 @@
+/**
+ * Native OS platform detection and design system adaptors for Hanzo.
+ *
+ * Configures native look/feel tailored to the user's OS:
+ * - iOS: Continuous squircles, Liquid Glass blurs, SF Pro fonts, safe area insets, specular highlights
+ * - Android: Material 3 tokens, Roboto/Google Sans, tonal elevations, ripple curves
+ * - macOS: Vibrant translucent glass, compact desktop paddings
+ * - Windows: Fluent/Mica acrylic glass, sharp modern geometry
+ * - Linux: Clean system lines, flat modern edges
+ */
+
+export type PlatformId = 'ios' | 'android' | 'macos' | 'windows' | 'linux'
+
+export interface PlatformProfile {
+  id: PlatformId
+  name: string
+  fontFamily: string
+  fontMono: string
+  radiusCard: number | string
+  radiusPill: number | string
+  glassBlur: number
+  glassSaturate: number
+  specularBorder: boolean
+  touchFeedback: 'spring' | 'ripple' | 'subtle'
+}
+
+export const PLATFORM_PROFILES: Record<PlatformId, PlatformProfile> = {
+  ios: {
+    id: 'ios',
+    name: 'Apple iOS',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", "SF Pro Display", sans-serif',
+    fontMono: '"SF Mono", ui-monospace, Menlo, monospace',
+    radiusCard: 22,
+    radiusPill: 9999,
+    glassBlur: 24,
+    glassSaturate: 190,
+    specularBorder: true,
+    touchFeedback: 'spring',
+  },
+  android: {
+    id: 'android',
+    name: 'Google Android',
+    fontFamily: 'Roboto, "Google Sans", system-ui, sans-serif',
+    fontMono: '"Roboto Mono", monospace',
+    radiusCard: 16,
+    radiusPill: 16,
+    glassBlur: 16,
+    glassSaturate: 130,
+    specularBorder: false,
+    touchFeedback: 'ripple',
+  },
+  macos: {
+    id: 'macos',
+    name: 'Apple macOS',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif',
+    fontMono: '"SF Mono", Menlo, monospace',
+    radiusCard: 12,
+    radiusPill: 9999,
+    glassBlur: 20,
+    glassSaturate: 160,
+    specularBorder: true,
+    touchFeedback: 'subtle',
+  },
+  windows: {
+    id: 'windows',
+    name: 'Microsoft Windows',
+    fontFamily: '"Segoe UI Variable", "Segoe UI", system-ui, sans-serif',
+    fontMono: '"Cascadia Code", Consolas, monospace',
+    radiusCard: 8,
+    radiusPill: 9999,
+    glassBlur: 18,
+    glassSaturate: 125,
+    specularBorder: false,
+    touchFeedback: 'subtle',
+  },
+  linux: {
+    id: 'linux',
+    name: 'Linux / Desktop',
+    fontFamily: 'system-ui, -apple-system, "Cantarell", sans-serif',
+    fontMono: '"Ubuntu Mono", monospace',
+    radiusCard: 10,
+    radiusPill: 9999,
+    glassBlur: 14,
+    glassSaturate: 110,
+    specularBorder: false,
+    touchFeedback: 'subtle',
+  },
+}
+
+const STORAGE_KEY = 'hanzo.mod.platform'
+
+/** Detects the current OS platform from user agent strings */
+export function detectPlatform(userAgent?: string): PlatformId {
+  const ua = (userAgent ?? (typeof navigator !== 'undefined' ? navigator.userAgent : '')).toLowerCase()
+  if (/iphone|ipad|ipod/.test(ua) || (typeof navigator !== 'undefined' && navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1)) {
+    return 'ios'
+  }
+  if (/android/.test(ua)) return 'android'
+  if (/macintosh|mac os x/.test(ua)) return 'macos'
+  if (/windows|win32|win64/.test(ua)) return 'windows'
+  if (/linux|x11/.test(ua)) return 'linux'
+  return 'ios'
+}
+
+/** Reads the user's active platform preference (stored or detected) */
+export function getActivePlatform(): PlatformId {
+  if (typeof window === 'undefined') return 'ios'
+  try {
+    const kept = window.localStorage.getItem(STORAGE_KEY) as PlatformId | null
+    if (kept && kept in PLATFORM_PROFILES) return kept
+  } catch {
+    // ignore storage restrictions
+  }
+  return detectPlatform()
+}
+
+/** Sets the user's preferred platform customization */
+export function setActivePlatform(platform: PlatformId | 'auto'): void {
+  if (typeof window === 'undefined') return
+  try {
+    if (platform === 'auto') {
+      window.localStorage.removeItem(STORAGE_KEY)
+    } else {
+      window.localStorage.setItem(STORAGE_KEY, platform)
+    }
+  } catch {
+    // ignore storage restrictions
+  }
+  applyPlatformTokens(platform === 'auto' ? detectPlatform() : platform)
+  window.dispatchEvent(new CustomEvent('hanzo:mod:change', { detail: { platform } }))
+}
+
+/** Statically stamps the platform CSS custom properties onto documentElement */
+export function applyPlatformTokens(platform: PlatformId): void {
+  if (typeof document === 'undefined') return
+  const profile = PLATFORM_PROFILES[platform] ?? PLATFORM_PROFILES.ios
+  const root = document.documentElement
+
+  root.setAttribute('data-platform', profile.id)
+  root.style.setProperty('--platform-font-sans', profile.fontFamily)
+  root.style.setProperty('--platform-font-mono', profile.fontMono)
+  root.style.setProperty('--platform-radius-card', typeof profile.radiusCard === 'number' ? `${profile.radiusCard}px` : profile.radiusCard)
+  root.style.setProperty('--platform-radius-pill', typeof profile.radiusPill === 'number' ? `${profile.radiusPill}px` : profile.radiusPill)
+  root.style.setProperty('--glass-blur', `${profile.glassBlur}px`)
+  root.style.setProperty('--glass-saturate', `${profile.glassSaturate}%`)
+}

package/src/theme.ts

@@ -0,0 +1,193 @@
+import { PLATFORM_PROFILES, type PlatformId, applyPlatformTokens } from './platform'
+
+export interface ModTheme {
+  id: string
+  name: string
+  description?: string
+  author?: string
+  org?: string
+  platform?: PlatformId
+  fontHeading?: string
+  fontBody?: string
+  fontMono?: string
+  customFontUrl?: string
+  primary?: string
+  accent?: string
+  glassTint?: string
+  glassBlur?: number
+  radius?: number
+  density?: 'compact' | 'comfortable' | 'default'
+  customCss?: string
+}
+
+export const BUILTIN_MODS: ModTheme[] = [
+  {
+    id: 'ios-liquid',
+    name: 'Apple iOS Liquid',
+    description: 'Continuous squircles, high-specular liquid glass, and Apple SF Pro typography.',
+    author: 'Hanzo Design',
+    platform: 'ios',
+    glassBlur: 24,
+    radius: 22,
+    density: 'comfortable',
+  },
+  {
+    id: 'android-material',
+    name: 'Android Material 3',
+    description: 'Google Material 3 tonal elevations, Roboto Sans, and smooth dynamic rounded cards.',
+    author: 'Hanzo Design',
+    platform: 'android',
+    glassBlur: 16,
+    radius: 16,
+    density: 'default',
+  },
+  {
+    id: 'macos-vibrant',
+    name: 'macOS Vibrant',
+    description: 'Translucent sidebars, vibrant visual effect filters, and clean desktop density.',
+    author: 'Hanzo Design',
+    platform: 'macos',
+    glassBlur: 20,
+    radius: 12,
+    density: 'compact',
+  },
+  {
+    id: 'windows-fluent',
+    name: 'Windows Mica Fluent',
+    description: 'Microsoft Fluent Design Mica acrylic and Segoe UI Variable geometry.',
+    author: 'Hanzo Design',
+    platform: 'windows',
+    glassBlur: 18,
+    radius: 8,
+    density: 'default',
+  },
+  {
+    id: 'cyber-zen',
+    name: 'Cyber Zen (OLED)',
+    description: 'High contrast deep OLED black with electric cyan and magenta accents.',
+    author: 'Hanzo Labs',
+    platform: 'ios',
+    primary: '#00f0ff',
+    accent: '#ff007f',
+    glassBlur: 28,
+    radius: 20,
+    density: 'comfortable',
+  },
+  {
+    id: 'nordic-frost',
+    name: 'Nordic Frost',
+    description: 'Pure arctic monochrome glass, high clarity, and minimalist typography.',
+    author: 'Hanzo Design',
+    platform: 'macos',
+    primary: '#e2e8f0',
+    accent: '#38bdf8',
+    glassBlur: 22,
+    radius: 14,
+    density: 'default',
+  },
+]
+
+const ORG_MOD_KEY = (orgId: string) => `hanzo.mod.org.${orgId}`
+const ACTIVE_MOD_KEY = 'hanzo.mod.active'
+
+/** Serializes a theme mod to JSON for exporting/sharing */
+export function exportMod(mod: ModTheme): string {
+  return JSON.stringify(mod, null, 2)
+}
+
+/** Parses and validates an imported mod JSON string */
+export function importMod(json: string): ModTheme {
+  const parsed = JSON.parse(json) as Partial<ModTheme>
+  if (!parsed || typeof parsed !== 'object' || !parsed.name) {
+    throw new Error('Invalid Hanzo mod: missing theme name')
+  }
+  return {
+    id: parsed.id || `mod-${Date.now()}`,
+    name: String(parsed.name).slice(0, 64),
+    description: parsed.description ? String(parsed.description).slice(0, 256) : undefined,
+    author: parsed.author ? String(parsed.author).slice(0, 64) : undefined,
+    org: parsed.org,
+    platform: parsed.platform && parsed.platform in PLATFORM_PROFILES ? parsed.platform : undefined,
+    fontHeading: parsed.fontHeading,
+    fontBody: parsed.fontBody,
+    fontMono: parsed.fontMono,
+    customFontUrl: parsed.customFontUrl,
+    primary: parsed.primary,
+    accent: parsed.accent,
+    glassTint: parsed.glassTint,
+    glassBlur: typeof parsed.glassBlur === 'number' ? parsed.glassBlur : undefined,
+    radius: typeof parsed.radius === 'number' ? parsed.radius : undefined,
+    density: parsed.density,
+    customCss: parsed.customCss,
+  }
+}
+
+/** Creates a new mod derived from an existing base theme */
+export function forkMod(base: ModTheme, overrides: Partial<ModTheme>): ModTheme {
+  return {
+    ...base,
+    ...overrides,
+    id: overrides.id || `${base.id}-fork-${Date.now().toString(36)}`,
+    name: overrides.name || `${base.name} (Mod)`,
+  }
+}
+
+/** Applies a theme mod dynamically to the page */
+export function applyMod(mod: ModTheme): void {
+  if (typeof document === 'undefined') return
+  const root = document.documentElement
+
+  if (mod.platform) {
+    applyPlatformTokens(mod.platform)
+  }
+
+  if (mod.primary) root.style.setProperty('--primary', mod.primary)
+  if (mod.accent) root.style.setProperty('--accent', mod.accent)
+  if (mod.glassTint) root.style.setProperty('--liquid-glass-bg', mod.glassTint)
+  if (typeof mod.glassBlur === 'number') root.style.setProperty('--glass-blur', `${mod.glassBlur}px`)
+  if (typeof mod.radius === 'number') root.style.setProperty('--radius', `${mod.radius}px`)
+  if (mod.fontHeading) root.style.setProperty('--font-heading', mod.fontHeading)
+  if (mod.fontBody) root.style.setProperty('--font-body', mod.fontBody)
+  if (mod.fontMono) root.style.setProperty('--font-mono', mod.fontMono)
+
+  // Inject custom CSS if defined
+  let styleEl = document.getElementById('hanzo-custom-mod-css')
+  if (mod.customCss) {
+    if (!styleEl) {
+      styleEl = document.createElement('style')
+      styleEl.id = 'hanzo-custom-mod-css'
+      document.head.appendChild(styleEl)
+    }
+    styleEl.textContent = mod.customCss
+  } else if (styleEl) {
+    styleEl.remove()
+  }
+
+  try {
+    window.localStorage.setItem(ACTIVE_MOD_KEY, JSON.stringify(mod))
+    window.dispatchEvent(new CustomEvent('hanzo:mod:applied', { detail: { mod } }))
+  } catch {
+    // ignore
+  }
+}
+
+/** Saves an organization-scoped mod configuration */
+export function saveOrgMod(orgId: string, mod: ModTheme): void {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(ORG_MOD_KEY(orgId), JSON.stringify({ ...mod, org: orgId }))
+  } catch {
+    // ignore
+  }
+}
+
+/** Gets the active mod for an organization */
+export function getOrgMod(orgId: string): ModTheme | null {
+  if (typeof window === 'undefined') return null
+  try {
+    const raw = window.localStorage.getItem(ORG_MOD_KEY(orgId))
+    return raw ? (JSON.parse(raw) as ModTheme) : null
+  } catch {
+    return null
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": false,
+    "strictNullChecks": false,
+    "noImplicitAny": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node", "react"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.