@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/theme/utils/GlobalStyles.ts

@@ -0,0 +1,88 @@
+import { createGlobalStyle } from 'styled-components'
+import { themeToCssVars } from './cssVariables.js'
+
+export const GlobalStyles = createGlobalStyle`
+	@import url('https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Source+Sans+3:ital,wght@0,200..900;1,200..900&display=swap');
+
+	*,
+	*::before,
+	*::after {
+		box-sizing: border-box;
+	}
+
+	html,
+	body,
+	#root {
+		height: 100%;
+		width: 100%;
+		margin: 0;
+	}
+
+	:root {
+		${({ theme }) => themeToCssVars(theme)}
+	}
+
+	body {
+		font-family: var(--platform-typography-font-family);
+		font-size: var(--platform-typography-font-size-base);
+		line-height: var(--platform-typography-line-height-base);
+		color: var(--platform-colors-text);
+		background: var(--platform-colors-bg);
+		-webkit-font-smoothing: antialiased;
+		-moz-osx-font-smoothing: grayscale;
+		overflow: hidden;
+	}
+
+	::selection {
+		background: var(--platform-colors-selection);
+	}
+
+	:focus-visible {
+		outline: 2px solid var(--platform-colors-focus);
+		outline-offset: 2px;
+	}
+
+	:focus:not(:focus-visible) {
+		outline: none;
+	}
+
+	button {
+		font: inherit;
+		color: inherit;
+		cursor: pointer;
+		border: none;
+		background: none;
+	}
+
+	a {
+		color: var(--platform-colors-accent);
+		text-decoration: none;
+	}
+
+	a:hover {
+		text-decoration: underline;
+	}
+
+	* {
+		scrollbar-width: thin;
+		scrollbar-color: var(--platform-colors-border) transparent;
+	}
+
+	*::-webkit-scrollbar {
+		width: 8px;
+		height: 8px;
+	}
+
+	*::-webkit-scrollbar-track {
+		background: transparent;
+	}
+
+	*::-webkit-scrollbar-thumb {
+		background-color: var(--platform-colors-border);
+		border-radius: 999px;
+	}
+
+	*::-webkit-scrollbar-thumb:hover {
+		background-color: var(--platform-colors-border-strong);
+	}
+`

package/src/theme/utils/appFrameDocumentStyles.d.mts

@@ -0,0 +1,5 @@
+export declare const PLATFORM_APP_FRAME_BASE_STYLE_ID: 'platform-app-frame-base'
+
+export declare const APP_FRAME_DOCUMENT_STYLES_CSS: string
+
+export function injectAppFrameDocumentStyles(doc?: Document): void

package/src/theme/utils/appFrameDocumentStyles.mjs

@@ -0,0 +1,89 @@
+/** Injected once per iframe document by AppFrame / applyThemeFromHost. */
+import { injectPlatformFontStylesheet } from '../platformFont.mjs'
+
+export const PLATFORM_APP_FRAME_BASE_STYLE_ID = 'platform-app-frame-base'
+
+export const APP_FRAME_DOCUMENT_STYLES_CSS = `
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  html,
+  body,
+  #root {
+    height: 100%;
+    width: 100%;
+    margin: 0;
+  }
+
+  body {
+    overflow: hidden;
+    font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+    font-size: var(--platform-typography-font-size-base);
+    line-height: var(--platform-typography-line-height-base);
+    color: var(--platform-colors-text);
+    background: var(--platform-colors-app-viewport);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  ::selection {
+    background: var(--platform-colors-selection);
+  }
+
+  button {
+    font: inherit;
+    color: inherit;
+    cursor: pointer;
+    border: none;
+    background: none;
+  }
+
+  a {
+    color: var(--platform-colors-accent);
+    text-decoration: none;
+  }
+
+  a:hover {
+    text-decoration: underline;
+  }
+
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: var(--platform-colors-border) transparent;
+  }
+
+  *::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+
+  *::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-thumb {
+    background-color: var(--platform-colors-border);
+    border-radius: 999px;
+  }
+
+  *::-webkit-scrollbar-thumb:hover {
+    background-color: var(--platform-colors-border-strong);
+  }
+`
+
+/**
+ * @param {Document} [doc]
+ */
+export function injectAppFrameDocumentStyles(doc = document) {
+  if (doc.getElementById(PLATFORM_APP_FRAME_BASE_STYLE_ID)) return
+
+  injectPlatformFontStylesheet(doc)
+
+  const el = doc.createElement('style')
+  el.id = PLATFORM_APP_FRAME_BASE_STYLE_ID
+  el.textContent = APP_FRAME_DOCUMENT_STYLES_CSS
+  doc.head.appendChild(el)
+}

package/src/theme/utils/appFrameDocumentStyles.ts

@@ -0,0 +1,5 @@
+export {
+  APP_FRAME_DOCUMENT_STYLES_CSS,
+  PLATFORM_APP_FRAME_BASE_STYLE_ID,
+  injectAppFrameDocumentStyles,
+} from './appFrameDocumentStyles.mjs'

package/src/theme/utils/applyTheme.ts

@@ -0,0 +1,50 @@
+import { normalizeSurfacePaletteId } from '../buildThemeBridgePayload.js'
+import { PlatformTheme } from '../tokens.js'
+import {
+  PLATFORM_THEME_PREFIX,
+  themeToCssVars,
+  themeToRootCssBlock,
+} from './cssVariables.js'
+
+const ROOT_STYLE_ID = 'platform-theme-vars'
+
+/** Apply theme CSS variables to a document (shell root or plugin iframe). */
+export function applyThemeToDocument(
+  doc: Document,
+  theme: PlatformTheme,
+  options?: {
+    selector?: string
+    styleId?: string
+    surfacePaletteId?: string | null
+  },
+): void {
+  const selector = options?.selector ?? ':root'
+  const styleId = options?.styleId ?? ROOT_STYLE_ID
+  const css = themeToRootCssBlock(theme, selector, PLATFORM_THEME_PREFIX)
+
+  let el = doc.getElementById(styleId)
+  if (!el) {
+    el = doc.createElement('style')
+    el.id = styleId
+    doc.head.appendChild(el)
+  }
+  el.textContent = css
+
+  const root = doc.documentElement
+  root.dataset.platformTheme = theme.mode
+
+  const paletteId = normalizeSurfacePaletteId(options?.surfacePaletteId)
+  if (paletteId) {
+    root.dataset.platformSurfacePalette = paletteId
+  } else {
+    delete root.dataset.platformSurfacePalette
+  }
+}
+
+/** Serialized vars only (e.g. inline style on a host element). */
+export function themeToInlineStyle(
+  theme: PlatformTheme,
+  prefix = PLATFORM_THEME_PREFIX,
+): string {
+  return themeToCssVars(theme, prefix).replace(/\n/g, ' ')
+}

package/src/theme/utils/cssVariables.ts

@@ -0,0 +1,49 @@
+import { PlatformTheme } from '../tokens.js'
+
+export const PLATFORM_THEME_PREFIX = 'platform'
+
+/** "accentMuted" → "accent-muted" */
+export function camelToCssVarKey(segment: string): string {
+  return segment.replace(/[A-Z]/g, match => `-${match.toLowerCase()}`)
+}
+
+/**
+ * Flatten a theme object into CSS custom property declarations.
+ *
+ * @example
+ * themeToCssVars(darkTheme)
+ * // "--platform-colors-bg: #0f1419;\n--platform-spacing-md: 16px;"
+ */
+export function themeToCssVars(
+  theme: PlatformTheme,
+  prefix = PLATFORM_THEME_PREFIX,
+): string {
+  const lines: string[] = []
+
+  function walk(obj: Record<string, unknown>, path: string[]): void {
+    for (const [key, value] of Object.entries(obj)) {
+      const varPath = [...path, camelToCssVarKey(key)]
+      if (
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+      ) {
+        walk(value as Record<string, unknown>, varPath)
+      } else {
+        lines.push(`--${prefix}-${varPath.join('-')}: ${value};`)
+      }
+    }
+  }
+
+  walk(theme as unknown as Record<string, unknown>, [])
+  return lines.join('\n')
+}
+
+/** Full `:root { … }` block for document or iframe injection. */
+export function themeToRootCssBlock(
+  theme: PlatformTheme,
+  selector = ':root',
+  prefix = PLATFORM_THEME_PREFIX,
+): string {
+  return `${selector} {\n${themeToCssVars(theme, prefix)}\n}`
+}

package/src/theme/utils/useInjectThemeIntoIframe.ts

@@ -0,0 +1,40 @@
+import { useEffect, type RefObject } from 'react'
+import { applyThemeToDocument } from './applyTheme.js'
+import type { PlatformTheme } from '../tokens.js'
+
+const IFRAME_THEME_STYLE_ID = 'platform-theme-vars-embedded'
+
+/**
+ * Mirrors the active shell theme into an embedded app iframe via CSS variables.
+ * Works only when parent and iframe are same-origin (e.g. module entrypoints).
+ * Dev-url plugins on another port are cross-origin — use bridge `theme.changed`
+ * and `applyThemeFromHost` / `usePlatformThemeFromBridge` instead.
+ */
+export function useInjectThemeIntoIframe(
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+  theme: PlatformTheme,
+  enabled: boolean,
+): void {
+  useEffect(() => {
+    if (!enabled) return
+
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    const apply = (): void => {
+      const doc = iframe.contentDocument
+      if (!doc) return
+      applyThemeToDocument(doc, theme, {
+        selector: ':root',
+        styleId: IFRAME_THEME_STYLE_ID,
+      })
+    }
+
+    iframe.addEventListener('load', apply)
+    apply()
+
+    return () => {
+      iframe.removeEventListener('load', apply)
+    }
+  }, [iframeRef, theme, enabled])
+}

package/src/utils/extensionIconMap.ts

@@ -0,0 +1,123 @@
+import type { LucideIcon } from 'lucide-react'
+import {
+  Archive,
+  Braces,
+  File,
+  FileAudio,
+  FileCode2,
+  FileImage,
+  FileSpreadsheet,
+  FileText,
+  FileType,
+  FileVideo,
+  Folder,
+  Globe,
+  Sheet,
+} from 'lucide-react'
+
+export type ExtensionIconMap = Partial<Record<string, LucideIcon>> & {
+  _: LucideIcon
+}
+
+/**
+ * File key → Lucide icon.
+ * Use `dir` for directories; otherwise normalized extension (no dot).
+ * `_` is the default fallback.
+ *
+ * @example
+ * const ext = isDirectory ? 'dir' : normalizeExtension(extension)
+ * const Icon = switchOn(ext, extensionIconMap) ?? extensionIconMap._
+ */
+export const extensionIconMap: ExtensionIconMap = {
+  dir: Folder,
+
+  // Documents
+  pdf: FileType,
+  txt: FileText,
+  md: FileText,
+  markdown: FileText,
+  rtf: FileText,
+  doc: FileText,
+  docx: FileText,
+
+  // Web
+  html: Globe,
+  htm: Globe,
+  css: FileCode2,
+  scss: FileCode2,
+  sass: FileCode2,
+  less: FileCode2,
+
+  // Code / data
+  json: Braces,
+  jsonc: Braces,
+  json5: Braces,
+  yaml: Braces,
+  yml: Braces,
+  toml: Braces,
+  xml: Braces,
+  csv: Sheet,
+  tsv: Sheet,
+  xls: FileSpreadsheet,
+  xlsx: FileSpreadsheet,
+  ods: FileSpreadsheet,
+  ts: FileCode2,
+  tsx: FileCode2,
+  js: FileCode2,
+  jsx: FileCode2,
+  mjs: FileCode2,
+  cjs: FileCode2,
+  py: FileCode2,
+  rb: FileCode2,
+  go: FileCode2,
+  rs: FileCode2,
+  java: FileCode2,
+  kt: FileCode2,
+  swift: FileCode2,
+  c: FileCode2,
+  cpp: FileCode2,
+  h: FileCode2,
+  hpp: FileCode2,
+  cs: FileCode2,
+  php: FileCode2,
+  sh: FileCode2,
+  bash: FileCode2,
+  zsh: FileCode2,
+  sql: FileCode2,
+  graphql: FileCode2,
+  gql: FileCode2,
+  vue: FileCode2,
+  svelte: FileCode2,
+
+  // Media
+  png: FileImage,
+  jpg: FileImage,
+  jpeg: FileImage,
+  gif: FileImage,
+  webp: FileImage,
+  svg: FileImage,
+  bmp: FileImage,
+  ico: FileImage,
+  mp4: FileVideo,
+  mov: FileVideo,
+  webm: FileVideo,
+  ogv: FileVideo,
+  mkv: FileVideo,
+  mp3: FileAudio,
+  m4a: FileAudio,
+  wav: FileAudio,
+  ogg: FileAudio,
+  flac: FileAudio,
+
+  // Archives
+  zip: Archive,
+  tar: Archive,
+  gz: Archive,
+  tgz: Archive,
+  bz2: Archive,
+  xz: Archive,
+  '7z': Archive,
+  rar: Archive,
+
+  _: File,
+}

package/src/utils/generalUtils.ts

@@ -0,0 +1,157 @@
+/**
+ * General-purpose utility functions.
+ * No DOM, no React, no Electron — safe for main and renderer.
+ */
+
+// ---- Deep access ----
+
+/** Safe deep property access. Returns defaultValue if path resolves to undefined. */
+export function get<T = unknown>(
+  obj: unknown,
+  path: string | string[],
+  defaultValue?: T,
+): T | undefined {
+  if (obj == null) return defaultValue
+  const keys = Array.isArray(path) ? path : path.split('.')
+  let result: unknown = obj
+  for (const key of keys) {
+    result = (result as Record<string, unknown>)?.[key]
+    if (result === undefined) return defaultValue
+  }
+  return (result ?? defaultValue) as T | undefined
+}
+
+// ---- Type guards ----
+
+export const isPlainObject = (
+  value: unknown,
+): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+export const isFunction = (
+  value: unknown,
+): value is (...args: unknown[]) => unknown => typeof value === 'function'
+
+// ---- Object iteration ----
+
+export const mapEntries = <K extends string, V, R>(
+  obj: Record<K, V>,
+  cb: (key: K, value: V) => R,
+): R[] => Object.entries(obj).map(([k, v]) => cb(k as K, v as V))
+
+export const filterEntries = <K extends string, V>(
+  obj: Record<K, V>,
+  cb: (key: K, value: V) => boolean,
+): Array<[K, V]> =>
+  (Object.entries(obj) as Array<[K, V]>).filter(([k, v]) => cb(k, v))
+
+// ---- Conditional spreads ----
+
+/** Conditionally return array items for array spread. */
+export const arrIf = <T>(
+  condition: boolean,
+  item: T | T[],
+  fallback: T[] = [],
+): T[] => {
+  if (condition) return Array.isArray(item) ? item : [item]
+  return fallback
+}
+
+// ---- Switch helpers ----
+
+/**
+ * Exhaustive-style value lookup — replaces switch/case for simple
+ * key → value mappings. `_` is an optional fallback for unmatched keys.
+ */
+export const switchOn = <K extends PropertyKey, R>(
+  key: K,
+  cases: Partial<Record<K, R>> & { _?: R },
+): R | undefined => (key in cases ? cases[key as K] : cases._)
+
+/**
+ * Lazy variant of switchOn — calls the matched function so React
+ * branches aren't evaluated until needed.
+ */
+export const callOn = <K extends PropertyKey, R>(
+  key: K,
+  cases: Partial<Record<K, () => R>> & { _?: () => R },
+): R | undefined => (cases[key as K] ?? cases._)?.()
+
+// ---- JSON ----
+
+/** Safe JSON parse. Returns fallback on failure. */
+export const safeParse = <T = Record<string, unknown>>(
+  str: string,
+  fallback: T = {} as T,
+): T => {
+  try {
+    return JSON.parse(str) as T
+  } catch {
+    return (str as unknown as T) ?? fallback
+  }
+}
+
+// ---- String casing ----
+
+/** "camelCaseString" → "Camel Case String" */
+export const camelCaseToCapital = (str: string): string => {
+  if (!str) return ''
+  return str
+    .replace(/([A-Z])/g, ' $1')
+    .split(' ')
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ')
+}
+
+/** "snake_case_string" (or "kebab-case") → "Snake Case String" */
+export const snakeCaseToHuman = (str: string): string => {
+  if (!str) return ''
+  return str
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, c => c.toUpperCase())
+}
+
+/** "wait For Assignment" | "do_not_return" → "waitForAssignment" */
+export const toCamelCase = (str: string): string => {
+  if (!str) return ''
+  if (/^[a-z][a-zA-Z0-9]*$/.test(str)) return str
+
+  const words = str
+    .replace(/[^a-zA-Z0-9\s_-]/g, '')
+    .split(/[\s_-]+/)
+    .filter(Boolean)
+
+  return words
+    .map((word, i) =>
+      i === 0
+        ? word.toLowerCase()
+        : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase(),
+    )
+    .join('')
+}
+
+/** "camelCase" | "snake_case" → "Camel case" */
+export const toHumanReadable = (str: string): string => {
+  if (!str) return ''
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .replace(/^\w/, c => c.toUpperCase())
+}
+
+/** "my-chapter-file.md" → "My Chapter File" */
+export const slugToTitle = (slug: string): string =>
+  slug
+    .replace(/\.md$/, '')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ') || 'Untitled'
+
+/** Strip leading dot and lowercase — `".PDF"` → `"pdf"`. */
+export const normalizeExtension = (extension: string): string =>
+  extension.toLowerCase().replace(/^\./, '')