@owdproject/react-theme-win95 0.0.0-stage → 4.0.0-alpha.3

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @owdproject/react-theme-win95
 
-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.
+Windows 95 theme for **Open Web Desktop**, built with **React** and
+[React95](https://react95.io).
+
+- **Engine**: [`@owdproject/core`](https://github.com/owdproject/core) — headless windows/apps/workspaces.
+- **Bridges**: [`@owdproject/react`](https://github.com/owdproject/core) — `useSyncExternalStore` hooks.
+- **UI**: [`@owdproject/react-kit-react95`](../owd-kit-react95) — [React95](https://react95.io) `@react95/core` integration.
+
+This is a **minimal vertical slice**: a working desktop shell (background, draggable/resizable
+React95 windows, task bar, start menu) plus two demo apps. It proves the whole React chain works
+end-to-end on top of the OWD engine.
+
+## Run it
+
+```bash
+# from the repo root (client/)
+pnpm install
+pnpm --filter @owdproject/react-theme-win95 dev
+# open http://localhost:5173
+```
+
+## Use it
+
+```tsx
+import { createDesktop } from '@owdproject/core'
+import { DesktopShell } from '@owdproject/react-theme-win95'
+import '@owdproject/react-kit-react95/styles.css'
+import '@owdproject/react-theme-win95/styles.css'
+
+const desktop = createDesktop()
+
+export default function App() {
+  return <DesktopShell desktop={desktop} watermark="React win95" />
+}
+```
+
+### Custom apps
+
+```tsx
+import type { DesktopApp } from '@owdproject/react-theme-win95'
+import { Notepad } from '@react95/icons'
+
+const apps: DesktopApp[] = [
+  {
+    id: 'hello',
+    title: 'Hello',
+    icon: <Notepad variant="16x16_4" />,
+    defaultSize: { width: 420, height: 300 },
+    component: ({ window, desktop }) => (
+      <div style={{ padding: 8 }}>
+        <p>Window {window.id}</p>
+        <button onClick={() => desktop.windows.closeWindow(window.id)}>Close</button>
+      </div>
+    ),
+  },
+]
+```
+
+## Architecture
+
+| File | Role |
+| --- | --- |
+| `src/DesktopShell.tsx` | Root shell: workarea, background, windows, start menu, task bar. |
+| `src/components/DesktopWindow.tsx` | One window. Reads state from `useWindowInstance`, moves/resizes via `useDesktopDrag` / `useDesktopResize`. Commits geometry back to the core on release. |
+| `src/components/SystemBar.tsx` | Task bar (React95 `Frame` + `Button`), driven by `useWindowManager`. |
+| `src/components/StartMenuPanel.tsx` | Start menu (React95 `List`). |
+| `src/apps/*` | Demo apps (`About`, `Notepad`). |
+| `src/theme.css` | Layout + app styles (visual primitives come from the kit). |
+| `playground/` | Vite + React playground app. |
+
+`@owdproject/core` is the single source of truth for window geometry and focus; React95 only
+renders the chrome, and `@owdproject/react` bridges the immutable core snapshots to React.
+
+> ℹ️ The playground Vite config includes a `build.rollupOptions.treeshake.moduleSideEffects`
+> rule for `@react95/*` (they ship no `sideEffects: false`), otherwise all 1000+ React95 icons
+> get bundled. Copy it into your own app's Vite config.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@owdproject/react-theme-win95",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0-alpha.3",
+  "description": "Windows 95 theme for Open Web Desktop built with React, @owdproject/core and @owdproject/react.",
+  "license": "MIT",
+  "author": {
+    "name": "Diego Villa",
+    "url": "https://github.com/dxlliv"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./styles.css": "./src/theme.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "playground"
+  ],
+  "scripts": {
+    "dev": "vite --config playground/vite.config.ts",
+    "build": "vite build --config playground/vite.config.ts",
+    "preview": "vite preview --config playground/vite.config.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@owdproject/core": "^4.0.0-alpha.3",
+    "@owdproject/react-kit-react95": "^4.0.0-alpha.3",
+    "@owdproject/react": "^4.0.0-alpha.3",
+    "@react95/icons": "^2.8.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "~6.0.3",
+    "vite": "^6.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/playground/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Open Web Desktop — React win95 theme</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/playground/src/App.tsx

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from 'react'
+import { createDesktop, type Desktop } from '@owdproject/core'
+import { DesktopShell } from '../../src'
+
+export function App() {
+  const desktopRef = useRef<Desktop | null>(null)
+  if (!desktopRef.current) {
+    desktopRef.current = createDesktop({
+      workspaces: ['workspace-1'],
+      workarea: { x: 0, y: 0, width: 0, height: 0 },
+    })
+  }
+  const desktop = desktopRef.current
+
+  // Open a welcome window on first mount.
+  useEffect(() => {
+    desktop.windows.createWindow({
+      id: 'about-welcome',
+      model: 'about',
+      applicationId: 'about',
+      config: {
+        title: 'About Open Web Desktop',
+        size: { width: 380, height: 240 },
+        position: { x: 72, y: 56 },
+      },
+    })
+  }, [desktop])
+
+  return <DesktopShell desktop={desktop} watermark="React win95" />
+}

package/playground/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import '@owdproject/react-kit-react95/styles.css'
+import '../../src/theme.css'
+import { App } from './App'
+
+const container = document.getElementById('root')
+if (!container) throw new Error('#root not found')
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/playground/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "types": ["vite/client"],
+    "noEmit": true
+  },
+  "include": ["src/**/*", "vite.config.ts"]
+}

package/playground/vite.config.ts

@@ -0,0 +1,43 @@
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+const here = fileURLToPath(new URL('.', import.meta.url))
+// pnpm workspace root (client/)
+const workspaceRoot = fileURLToPath(new URL('../../..', import.meta.url))
+
+export default defineConfig({
+  root: here,
+  plugins: [react()],
+  build: {
+    outDir: '../dist',
+    emptyOutDir: true,
+    rollupOptions: {
+      treeshake: {
+        // @react95/* ships no `sideEffects: false`, so Rollup otherwise keeps
+        // every icon/component module (and its CSS). Prune pure-JS modules but
+        // keep `.css`/`.css.mjs` so component styles still load.
+        moduleSideEffects(id) {
+          if (id.includes('@react95/')) return id.includes('.css')
+          return true
+        },
+      },
+    },
+  },
+  server: {
+    port: 5173,
+    fs: {
+      // Allow serving sources of the linked workspace packages.
+      allow: [workspaceRoot],
+    },
+  },
+  optimizeDeps: {
+    // Workspace packages are consumed as raw TypeScript sources.
+    exclude: [
+      '@owdproject/core',
+      '@owdproject/react',
+      '@owdproject/react-kit-react95',
+      '@owdproject/react-theme-win95',
+    ],
+  },
+})

package/src/DesktopShell.tsx

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import type { Desktop } from '@owdproject/core'
+import { useWindowManager } from '@owdproject/react'
+import { React95Provider } from '@owdproject/react-kit-react95'
+import { DesktopRuntimeContext } from './desktop-context'
+import { DesktopWindow } from './components/DesktopWindow'
+import { SystemBar } from './components/SystemBar'
+import { StartMenuPanel } from './components/StartMenuPanel'
+import { builtinApps } from './apps'
+import type { DesktopApp } from './types'
+
+const SYSTEMBAR_HEIGHT = 28
+
+export interface DesktopShellProps {
+  /** A `@owdproject/core` Desktop instance. */
+  desktop: Desktop
+  /** Applications exposed in the start menu / task bar. */
+  apps?: DesktopApp[]
+  /** Centered desktop watermark text. */
+  watermark?: ReactNode
+}
+
+/**
+ * Root Windows 95 desktop shell for React.
+ * Composes `@owdproject/react-kit-react95` chrome with `@owdproject/react` hooks
+ * and the headless `@owdproject/core` engine.
+ */
+export function DesktopShell({ desktop, apps = builtinApps, watermark = 'Open Web Desktop' }: DesktopShellProps) {
+  const rootRef = useRef<HTMLDivElement>(null)
+  const [startOpen, setStartOpen] = useState(false)
+  const idRef = useRef(0)
+  const { windows } = useWindowManager(desktop.windows)
+
+  const getWorkarea = useCallback(() => {
+    const el = rootRef.current
+    const width = el?.clientWidth ?? (typeof window !== 'undefined' ? window.innerWidth : 1024)
+    const height = (el?.clientHeight ?? (typeof window !== 'undefined' ? window.innerHeight : 768)) - SYSTEMBAR_HEIGHT
+    return { x: 0, y: 0, width, height }
+  }, [])
+
+  useEffect(() => {
+    const sync = () => desktop.workspaces.setWorkarea(getWorkarea())
+    sync()
+    window.addEventListener('resize', sync)
+    return () => window.removeEventListener('resize', sync)
+  }, [desktop, getWorkarea])
+
+  const runtime = useMemo(() => ({ desktop, getWorkarea }), [desktop, getWorkarea])
+
+  const launch = (app: DesktopApp) => {
+    idRef.current += 1
+    const count = windows.length
+    const size = app.defaultSize ?? { width: 480, height: 340 }
+    desktop.windows.createWindow({
+      id: `${app.id}-${idRef.current}`,
+      model: app.id,
+      applicationId: app.id,
+      config: {
+        title: app.title,
+        size,
+        position: { x: 48 + (count % 7) * 26, y: 40 + (count % 7) * 26 },
+      },
+    })
+    setStartOpen(false)
+  }
+
+  const activeWindows = windows.filter((win) => win.state.active !== false)
+  const appById = new Map(apps.map((app) => [app.id, app]))
+
+  return (
+    <DesktopRuntimeContext.Provider value={runtime}>
+      <React95Provider>
+        <div ref={rootRef} className="owd-shell" onPointerDown={() => setStartOpen(false)}>
+          <div className="owd-shell__desktop r95-owd-desktop">
+            {watermark ? <div className="owd-shell__watermark">{watermark}</div> : null}
+            {activeWindows.map((win) => (
+              <DesktopWindow key={win.id} window={win} app={appById.get(win.model)} />
+            ))}
+          </div>
+
+          {startOpen ? (
+            <div className="owd-shell__startmenu" onPointerDown={(event) => event.stopPropagation()}>
+              <StartMenuPanel apps={apps} onLaunch={launch} />
+            </div>
+          ) : null}
+
+          <SystemBar apps={apps} startActive={startOpen} onStartClick={() => setStartOpen((open) => !open)} />
+        </div>
+      </React95Provider>
+    </DesktopRuntimeContext.Provider>
+  )
+}

package/src/apps/About.tsx

@@ -0,0 +1,27 @@
+import { Computer } from '@react95/icons'
+import { Button } from '@owdproject/react-kit-react95'
+import type { DesktopAppRenderProps } from '../types'
+
+export function AboutApp({ window, desktop }: DesktopAppRenderProps) {
+  return (
+    <div className="owd-about">
+      <div className="owd-about__banner">
+        <Computer variant="32x32_4" />
+        <div>
+          <strong>Open Web Desktop</strong>
+          <div className="owd-about__small">React theme — win95 (React95)</div>
+        </div>
+      </div>
+      <hr className="owd-about__divider" />
+      <p className="owd-about__text">
+        Running on <code>@owdproject/core</code> + <code>@owdproject/react</code> +{' '}
+        <code>@react95/core</code>
+        <br />
+        Window <code>{window.id}</code> · model <code>{window.model}</code>
+      </p>
+      <div className="owd-about__actions">
+        <Button onClick={() => desktop.windows.closeWindow(window.id)}>OK</Button>
+      </div>
+    </div>
+  )
+}

package/src/apps/Notepad.tsx

@@ -0,0 +1,24 @@
+import { useState } from 'react'
+import type { DesktopAppRenderProps } from '../types'
+
+export function NotepadApp(_props: DesktopAppRenderProps) {
+  const [text, setText] = useState(
+    'Hello from a React window.\r\n\r\nDrag the title bar to move me, or grab an edge to resize.',
+  )
+  return (
+    <div className="owd-notepad">
+      <div className="owd-notepad__menu">
+        <span>File</span>
+        <span>Edit</span>
+        <span>Search</span>
+        <span>Help</span>
+      </div>
+      <textarea
+        className="owd-notepad__area"
+        value={text}
+        spellCheck={false}
+        onChange={(event) => setText(event.target.value)}
+      />
+    </div>
+  )
+}

package/src/apps/index.tsx

@@ -0,0 +1,24 @@
+import type { DesktopApp } from '../types'
+import { InfoBubble, Notepad } from '@react95/icons'
+import { AboutApp } from './About'
+import { NotepadApp } from './Notepad'
+
+/** Built-in apps shipped with the win95 React theme. */
+export const builtinApps: DesktopApp[] = [
+  {
+    id: 'about',
+    title: 'About Open Web Desktop',
+    icon: <InfoBubble variant="32x32_4" />,
+    defaultSize: { width: 380, height: 240 },
+    component: AboutApp,
+  },
+  {
+    id: 'notepad',
+    title: 'Untitled - Notepad',
+    icon: <Notepad variant="16x16_4" />,
+    defaultSize: { width: 480, height: 340 },
+    component: NotepadApp,
+  },
+]
+
+export { AboutApp, NotepadApp }

package/src/components/DesktopWindow.tsx

@@ -0,0 +1,133 @@
+import { useReducer, useRef, type CSSProperties } from 'react'
+import type { ResizeDirection, WindowBounds, WindowInstance, WindowState } from '@owdproject/core'
+import { useDesktopDrag, useDesktopResize, useWindowInstance } from '@owdproject/react'
+import { OwdWindow } from '@owdproject/react-kit-react95'
+import { useDesktopRuntime } from '../desktop-context'
+import type { DesktopApp } from '../types'
+
+const FALLBACK_SIZE = { width: 480, height: 340 }
+
+function readBounds(state: WindowState, fallback: { width: number; height: number }): WindowBounds {
+  const pos = state.position ?? {}
+  const size = state.size ?? {}
+  return {
+    x: pos.x ?? 0,
+    y: pos.y ?? 0,
+    width: typeof size.width === 'number' ? size.width : fallback.width,
+    height: typeof size.height === 'number' ? size.height : fallback.height,
+  }
+}
+
+export interface DesktopWindowProps {
+  window: WindowInstance
+  app?: DesktopApp
+}
+
+/**
+ * A single desktop window: reads live state from `@owdproject/react`'s
+ * `useWindowInstance`, drives move/resize through `@owdproject/core`'s pointer
+ * sessions (`useDesktopDrag` / `useDesktopResize`) and renders React95 window
+ * chrome via the kit's `OwdWindow`.
+ *
+ * While dragging, geometry is kept in local state for smoothness and committed
+ * back to the core engine on release.
+ */
+export function DesktopWindow({ window: instance, app }: DesktopWindowProps) {
+  const { desktop, getWorkarea } = useDesktopRuntime()
+  const { state } = useWindowInstance(instance)
+  const fallback = app?.defaultSize ?? FALLBACK_SIZE
+
+  const liveBounds = useRef<WindowBounds | null>(null)
+  const [, forceRender] = useReducer((n: number) => n + 1, 0)
+
+  const commit = (bounds: WindowBounds) => {
+    liveBounds.current = null
+    instance.setPosition({ x: bounds.x, y: bounds.y })
+    instance.setSize({ width: bounds.width, height: bounds.height })
+    forceRender()
+  }
+
+  const { startDrag } = useDesktopDrag({
+    getBounds: () => readBounds(instance.getSnapshot(), fallback),
+    getWorkarea,
+    onMove: (bounds) => {
+      liveBounds.current = bounds
+      forceRender()
+    },
+    onEnd: commit,
+    onCancel: () => {
+      liveBounds.current = null
+      forceRender()
+    },
+  })
+
+  const { startResize } = useDesktopResize({
+    getBounds: () => readBounds(instance.getSnapshot(), fallback),
+    minWidth: 180,
+    minHeight: 120,
+    onMove: (bounds) => {
+      liveBounds.current = bounds
+      forceRender()
+    },
+    onEnd: commit,
+    onCancel: () => {
+      liveBounds.current = null
+      forceRender()
+    },
+  })
+
+  const bounds = liveBounds.current ?? readBounds(state, fallback)
+  const maximized = state.maximized === true
+
+  const style: CSSProperties = {
+    left: bounds.x,
+    top: bounds.y,
+    width: bounds.width,
+    height: bounds.height,
+    zIndex: state.position?.z ?? 0,
+  }
+
+  const focus = () => desktop.windows.focusWindow(instance.id)
+  const AppComponent = app?.component
+
+  return (
+    <OwdWindow
+      title={app?.title ?? instance.config.title ?? instance.id}
+      icon={app?.icon}
+      active={state.focused}
+      maximized={maximized}
+      resizable={state.resizable !== false}
+      minimizable={state.minimizable !== false}
+      maximizable={state.maximizable !== false}
+      closable={state.destroyable !== false}
+      style={style}
+      onPointerDownCapture={focus}
+      onTitlePointerDown={(event) => {
+        if (event.button !== 0) return
+        focus()
+        startDrag(event.nativeEvent)
+      }}
+      onTitleDoubleClick={() => {
+        if (state.maximizable === false) return
+        instance.setLayout(maximized ? 'normal' : 'maximize', getWorkarea())
+      }}
+      onResizePointerDown={(event, direction) => {
+        if (event.button !== 0) return
+        focus()
+        startResize(event.nativeEvent, direction as ResizeDirection)
+      }}
+      onClose={() => desktop.windows.closeWindow(instance.id)}
+      onMinimize={() => instance.minimize()}
+      onToggleMaximize={() => {
+        if (state.maximizable === false) return
+        instance.setLayout(maximized ? 'normal' : 'maximize', getWorkarea())
+      }}
+    >
+      {AppComponent ? (
+        <AppComponent window={instance} desktop={desktop} />
+      ) : (
+        <div className="owd-window__empty">No component registered for “{instance.model}”.</div>
+      )}
+    </OwdWindow>
+  )
+}

package/src/components/StartMenuPanel.tsx

@@ -0,0 +1,32 @@
+import { PowerOff } from '@react95/icons'
+import { List } from '@owdproject/react-kit-react95'
+import type { DesktopApp } from '../types'
+
+export interface StartMenuPanelProps {
+  apps: DesktopApp[]
+  onLaunch: (app: DesktopApp) => void
+}
+
+/** Start menu built with React95 `List` + `List.Item`. */
+export function StartMenuPanel({ apps, onLaunch }: StartMenuPanelProps) {
+  return (
+    <div className="owd-startmenu">
+      <div className="owd-startmenu__rail">
+        <span>
+          Open Web <strong>Desktop</strong>
+        </span>
+      </div>
+      <List className="owd-startmenu__list">
+        {apps.map((app) => (
+          <List.Item key={app.id} icon={app.icon} onClick={() => onLaunch(app)}>
+            {app.title}
+          </List.Item>
+        ))}
+        <List.Divider />
+        <List.Item icon={<PowerOff variant="16x16_4" />} disabled>
+          Shut Down…
+        </List.Item>
+      </List>
+    </div>
+  )
+}

package/src/components/SystemBar.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react'
+import { Logo } from '@react95/icons'
+import { Button, Frame } from '@owdproject/react-kit-react95'
+import { useWindowManager } from '@owdproject/react'
+import { useDesktopRuntime } from '../desktop-context'
+import type { DesktopApp } from '../types'
+
+function useClock() {
+  const [now, setNow] = useState(() => new Date())
+  useEffect(() => {
+    const id = setInterval(() => setNow(new Date()), 10_000)
+    return () => clearInterval(id)
+  }, [])
+  return now
+}
+
+export interface SystemBarProps {
+  apps: DesktopApp[]
+  onStartClick: () => void
+  startActive: boolean
+}
+
+/**
+ * Bottom system bar built from React95 `Frame` + `Button` primitives.
+ * Unlike React95's own `TaskBar`, it is driven by the OWD window manager
+ * (`useWindowManager`), so it lists real `@owdproject/core` windows.
+ */
+export function SystemBar({ apps, onStartClick, startActive }: SystemBarProps) {
+  const { desktop } = useDesktopRuntime()
+  const { windows, focused } = useWindowManager(desktop.windows)
+  const now = useClock()
+
+  const appById = new Map(apps.map((app) => [app.id, app]))
+  const clock = now.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+
+  return (
+    <Frame className="owd-taskbar">
+      <Button
+        className={`owd-taskbar__start${startActive ? ' is-active' : ''}`}
+        onClick={onStartClick}
+        aria-pressed={startActive}
+      >
+        <Logo variant="16x16_4" />
+        <span className="owd-taskbar__start-label">Start</span>
+      </Button>
+
+      <Frame className="owd-taskbar__tasks">
+        {windows.map((win) => {
+          const app = appById.get(win.model)
+          const title = app?.title ?? win.config.title ?? win.id
+          const isActive = focused?.id === win.id
+          return (
+            <Button
+              key={win.id}
+              className={`owd-task${isActive ? ' is-active' : ''}`}
+              title={title}
+              onClick={() => {
+                if (win.state.active === false) win.unminimize()
+                desktop.windows.focusWindow(win.id)
+              }}
+            >
+              <span className="owd-task__label">{title}</span>
+            </Button>
+          )
+        })}
+      </Frame>
+
+      <Frame className="owd-taskbar__tray">
+        <span className="owd-taskbar__clock">{clock}</span>
+      </Frame>
+    </Frame>
+  )
+}

package/src/desktop-context.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react'
+import type { Desktop, DesktopWorkareaRect } from '@owdproject/core'
+
+export interface DesktopRuntime {
+  desktop: Desktop
+  /** Current usable desktop area (excluding the system bar), in shell coordinates. */
+  getWorkarea: () => DesktopWorkareaRect
+}
+
+export const DesktopRuntimeContext = createContext<DesktopRuntime | null>(null)
+
+export function useDesktopRuntime(): DesktopRuntime {
+  const runtime = useContext(DesktopRuntimeContext)
+  if (!runtime) {
+    throw new Error('[owd-react-theme-win95] useDesktopRuntime() must be used inside <DesktopShell>.')
+  }
+  return runtime
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @owdproject/react-theme-win95
+ * Windows 95 Open Web Desktop theme for React.
+ *
+ * Built on the headless `@owdproject/core` engine, the `@owdproject/react`
+ * hooks and the `@owdproject/react-kit-react95` visual primitives.
+ */
+
+export { DesktopShell, type DesktopShellProps } from './DesktopShell'
+export { DesktopWindow, type DesktopWindowProps } from './components/DesktopWindow'
+export { SystemBar, type SystemBarProps } from './components/SystemBar'
+export { StartMenuPanel, type StartMenuPanelProps } from './components/StartMenuPanel'
+export { useDesktopRuntime, DesktopRuntimeContext, type DesktopRuntime } from './desktop-context'
+export { builtinApps, AboutApp, NotepadApp } from './apps'
+export type { DesktopApp, DesktopAppRenderProps } from './types'
+
+// Re-export the kit primitives so consumers get one entry point.
+export * from '@owdproject/react-kit-react95'

package/src/theme.css

@@ -0,0 +1,217 @@
+/*
+ * @owdproject/react-theme-win95 — theme layout & app styles.
+ * Visual primitives come from @react95/core (via @owdproject/react-kit-react95).
+ */
+
+.owd-shell {
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+}
+
+.owd-shell__desktop {
+  position: absolute;
+  inset: 0 0 28px 0;
+  overflow: hidden;
+}
+
+.owd-shell__watermark {
+  position: absolute;
+  right: 16px;
+  bottom: 16px;
+  color: rgba(255, 255, 255, 0.6);
+  font-weight: bold;
+  text-shadow: 1px 1px 0 rgba(0, 0, 0, 0.35);
+  pointer-events: none;
+}
+
+.owd-shell__startmenu {
+  position: absolute;
+  left: 2px;
+  bottom: 28px;
+  z-index: 100000;
+}
+
+/* ----------------------------------------------------------- System bar */
+
+.owd-taskbar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px;
+  z-index: 90000;
+  background: var(--r95-color-material, #c3c7cb);
+  box-shadow:
+    inset 1px 1px 0 var(--r95-color-borderLightest, #fff),
+    inset -1px -1px 0 var(--r95-color-borderDark, #868a8e);
+}
+
+.owd-taskbar__start {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-weight: bold;
+  flex: 0 0 auto;
+}
+
+.owd-taskbar__start.is-active {
+  padding-top: 2px;
+  padding-left: 2px;
+}
+
+.owd-taskbar__start-label {
+  line-height: 1;
+}
+
+.owd-taskbar__tasks {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  background: transparent;
+  box-shadow: none;
+  overflow: hidden;
+}
+
+.owd-task {
+  display: inline-flex;
+  align-items: center;
+  min-width: 110px;
+  max-width: 168px;
+  overflow: hidden;
+}
+
+.owd-task.is-active {
+  box-shadow:
+    inset 1px 1px 0 var(--r95-color-borderDark, #868a8e),
+    inset -1px -1px 0 var(--r95-color-borderLightest, #fff);
+  background-color: var(--r95-color-borderLight, #d2d2d2);
+}
+
+.owd-task__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.owd-taskbar__tray {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  padding: 0 6px;
+  background: transparent;
+  box-shadow: none;
+}
+
+.owd-taskbar__clock {
+  padding: 0 2px;
+}
+
+/* ------------------------------------------------------------ Start menu */
+
+.owd-startmenu {
+  display: flex;
+  background: var(--r95-color-material, #c3c7cb);
+  border: 2px solid;
+  border-color: var(--r95-color-borderLight) var(--r95-color-borderDarkest)
+    var(--r95-color-borderDarkest) var(--r95-color-borderLight);
+  box-shadow: inset 1px 1px 0 var(--r95-color-borderLightest);
+}
+
+.owd-startmenu__rail {
+  width: 26px;
+  background: linear-gradient(180deg, #000e7a, #1084d0);
+  color: #fff;
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  padding: 8px 0;
+  font-weight: bold;
+  letter-spacing: 1px;
+}
+
+.owd-startmenu__list {
+  border: 0;
+  box-shadow: none;
+  background: transparent;
+  min-width: 190px;
+}
+
+/* ------------------------------------------------------- App: About box */
+
+.owd-about {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  height: 100%;
+  padding: 4px;
+  user-select: text;
+}
+
+.owd-about__banner {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.owd-about__small {
+  color: #404040;
+}
+
+.owd-about__divider {
+  width: 100%;
+  border: 0;
+  border-top: 1px solid var(--r95-color-borderDark);
+  border-bottom: 1px solid var(--r95-color-borderLight);
+}
+
+.owd-about__text {
+  margin: 0;
+  line-height: 1.5;
+}
+
+.owd-about__actions {
+  margin-top: auto;
+  display: flex;
+  justify-content: flex-end;
+}
+
+/* --------------------------------------------------------- App: Notepad */
+
+.owd-notepad {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.owd-notepad__menu {
+  display: flex;
+  gap: 14px;
+  padding: 2px 6px;
+}
+
+.owd-notepad__area {
+  flex: 1 1 auto;
+  width: 100%;
+  resize: none;
+  border: 0;
+  outline: none;
+  padding: 4px;
+  background: #fff;
+  font-family: 'Lucida Console', 'Courier New', monospace;
+  font-size: 12px;
+  line-height: 1.4;
+}
+
+.owd-window__empty {
+  padding: 8px;
+  color: #404040;
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+import type { ComponentType, ReactElement } from 'react'
+import type { Desktop, WindowInstance } from '@owdproject/core'
+
+/** Props passed to every application window component. */
+export interface DesktopAppRenderProps {
+  window: WindowInstance
+  desktop: Desktop
+}
+
+/** A React application that can be launched from the start menu / task bar. */
+export interface DesktopApp {
+  id: string
+  title: string
+  /** React95 icon used in the start menu, window title bar and task bar. */
+  icon?: ReactElement
+  defaultSize?: { width: number; height: number }
+  component: ComponentType<DesktopAppRenderProps>
+}