deskforge 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "json.schemaDownload.enable": false
+}

package/README.md

@@ -0,0 +1,547 @@
+# DeskForge Framework Documentation
+
+DeskForge is a lightweight, component-oriented application framework for building screen-based UI trees and rendering them to images or other outputs. The current repository ships a small but practical foundation for:
+
+- building a declarative node tree
+- routing between screens
+- rendering a tree with the renderer package
+- exporting the output to PNG or other formats
+
+The project is organized as a monorepo with separate packages for core rendering, routing, UI, state, theming, device integration, and more.
+
+> This documentation reflects the current implementation in this repository and focuses on the patterns demonstrated by the example app in examples/deskforge-app.
+
+---
+
+## 1. What DeskForge is
+
+DeskForge is built around a simple idea:
+
+1. You describe your UI as a tree of nodes.
+2. Each node has a type, props, and children.
+3. A renderer walks that tree and draws it.
+4. A router lets you switch between screens.
+
+This model is intentionally simple and close to the rendering pipeline used by many UI systems, but it is currently aimed at a desktop-style, image-rendering workflow rather than a full browser runtime.
+
+### Core principles
+
+- Declarative UI composition using node trees
+- Screen-based navigation with route registration
+- Renderer-driven output for images and visual artifacts
+- Modular packages that can be used independently
+
+---
+
+## 2. Repository structure
+
+A typical DeskForge workspace contains:
+
+```text
+packages/
+  core/        # node tree, scheduler, component primitives
+  renderer/    # rendering engine
+  router/      # screen routing and navigation
+  ui/          # built-in UI primitives
+  state/       # state utilities
+  theme/       # theme tokens and styling
+  device/      # device integrations
+  ...
+examples/
+  deskforge-app/   # full example app
+```
+
+### Important packages
+
+- `@deskforge/core`: defines the underlying node model and factory helpers
+- `@deskforge/renderer`: renders the node tree to canvas-like output
+- `@deskforge/router`: handles route registration and navigation
+- `@deskforge/ui`: provides reusable UI building blocks
+
+---
+
+## 3. Installation
+
+If you are using the monorepo directly, install dependencies from the repository root:
+
+```bash
+cd /path/to/deskforge
+npm install
+```
+
+If you are building an app that depends on the published packages, install the relevant packages:
+
+```bash
+npm install @deskforge/core @deskforge/router @deskforge/renderer
+```
+
+You can also add the UI package:
+
+```bash
+npm install @deskforge/ui
+```
+
+## 4. Quick start: File-based routing
+
+DeskForge now includes a file-based router similar to **Expo Router** and **Next.js**. No need to register routes manually—your file structure becomes your routes:
+
+```ts
+import { FileRouter, ManifestBuilder, Screen } from '@deskforge/router'
+
+const HomeRoute = Screen(() => createNode('view', {}, []), {
+  title: 'Home',
+  layout: 'app',
+})
+
+const routes = new ManifestBuilder()
+  .add('index.ts', HomeRoute.component)
+  .add('about.ts', AboutScreen)
+  .add('note/[id].ts', NoteScreen)
+  .build()
+
+const router = new FileRouter(routes)
+
+router.navigate('/')
+router.navigate('/note/123')
+
+const node = router.render()
+renderer.renderNode(node)
+```
+
+See [FILE_BASED_ROUTER.md](FILE_BASED_ROUTER.md) for detailed documentation and examples.
+
+---
+
+## 5. Core concepts
+
+### 5.1 The node tree
+
+The building block of DeskForge is a node. Every UI element is represented by a node with:
+
+- `type`: the component type, such as `text`, `view`, or a custom component
+- `props`: properties that describe how the node should appear or behave
+- `children`: nested nodes
+
+The core package exposes `createNode` to construct nodes.
+
+```ts
+import { createNode } from '@deskforge/core'
+
+const node = createNode('view', {
+  style: { background: '#ffffff', padding: 16 },
+}, [])
+```
+
+A more realistic example looks like this:
+
+```ts
+import { createNode } from '@deskforge/core'
+
+const title = createNode('text', {
+  text: 'Hello DeskForge',
+  color: '#111827',
+  font: '24px sans-serif',
+})
+
+const layout = createNode('view', {
+  style: { padding: 24 },
+}, [title])
+```
+
+### 5.2 The renderer
+
+The renderer walks the node tree and produces visual output. In the current example app, the rendering flow is:
+
+1. create or compose a node tree
+2. pass it to the renderer
+3. save or display the result
+
+```ts
+import { Renderer } from '@deskforge/renderer'
+
+const renderer = new Renderer({
+  width: 800,
+  height: 600,
+  backgroundColor: '#f7f8fb',
+})
+
+renderer.renderNode(layout)
+await renderer.saveAs('./dist/output.png')
+```
+
+### 5.3 Screens and routes
+
+DeskForge uses routes mapping to screen components. A screen is simply a function that returns a node tree, and it can also carry Expo-style metadata such as a title and layout.
+
+```ts
+import { Screen } from '@deskforge/router'
+
+function HomeScreen() {
+  return createNode('view', {
+    style: { padding: 24 },
+  }, [])
+}
+
+const HomeRoute = Screen(HomeScreen, { title: 'Home', layout: 'app' })
+```
+
+You register screens with `Router`:
+
+```ts
+import { Router } from '@deskforge/router'
+
+Router({
+  home: HomeRoute,
+})
+```
+
+And navigate with:
+
+```ts
+Router.go('home')
+```
+
+---
+
+## 6. Building an app in DeskForge
+
+The simplest app has three parts:
+
+1. an entry point file, usually `App.ts`
+2. one or more screen files
+3. a small UI helper layer for creating views and text blocks
+
+The example app in `examples/deskforge-app` follows this pattern.
+
+### 6.1 Create the app entry point
+
+A basic entry file looks like this:
+
+```ts
+import * as fs from 'fs'
+import { Renderer } from '@deskforge/renderer'
+import { Router } from '@deskforge/router'
+import { HomeScreen } from './src/screens'
+
+Router({
+  home: HomeScreen,
+})
+
+function createRoot() {
+  return createNode('view', {
+    style: { background: '#f7f8fb', padding: 24 },
+  }, [])
+}
+
+async function main() {
+  fs.mkdirSync('./dist', { recursive: true })
+
+  const renderer = new Renderer({
+    width: 800,
+    height: 600,
+    backgroundColor: '#f7f8fb',
+  })
+
+  Router.go('home')
+  renderer.renderNode(createRoot())
+  await renderer.saveAs('./dist/app.png')
+}
+
+main().catch(console.error)
+```
+
+### 6.2 Create screen files
+
+A screen is a function that returns a node tree. The example uses a simple `Screen` helper to create a container.
+
+```ts
+import type { ScreenParams } from '@deskforge/router'
+import { Screen, Text, View } from '../ui/Responsive'
+
+export default function HomeScreen(params: ScreenParams = {}) {
+  return Screen({ style: { background: '#f8fafc', padding: 24 } })
+    .add(
+      View({ style: { background: '#ffffff', borderRadius: 24, padding: 24 } }),
+      Text('Home Screen', { style: { fontSize: 28, fontWeight: '700' } }),
+      Text('Welcome to DeskForge.', { style: { color: '#4b5563', fontSize: 16 } }),
+    )
+    .build()
+}
+```
+
+### 6.3 Register screens
+
+In the entry file or a shared bootstrapping module, register all screens:
+
+```ts
+import { Router } from '@deskforge/router'
+import { HomeScreen, DetailsScreen } from './src/screens'
+
+Router({
+  home: HomeRoute,
+  details: DetailsRoute,
+})
+```
+
+### 6.4 Navigate between screens
+
+```ts
+Router.go('details', { noteId: 'A1' })
+```
+
+The current router stores navigation history and exposes helpers such as:
+
+- `Router.go(name, params)`
+- `Router.back()`
+- `Router.forward()`
+- `Router.params()`
+- `Router.currentRoute()`
+
+---
+
+## 6. Using the example app
+
+The repository includes an example app in `examples/deskforge-app`. It demonstrates how to build a basic screen-based app.
+
+### Run the example
+
+```bash
+cd examples/deskforge-app
+npm install
+npm run build
+npm run start
+```
+
+This example renders images for the home and details screens into the `dist` folder.
+
+### Example layout
+
+```text
+examples/deskforge-app/
+  App.ts
+  src/
+    screens/
+      Home.ts
+      Details.ts
+      index.ts
+    ui/
+      Responsive.ts
+```
+
+---
+
+## 7. Creating your own UI layers
+
+Because DeskForge is still evolving, the most practical way to build UI is to define your own lightweight helper functions on top of the core node API.
+
+### Example: simple text and view helpers
+
+```ts
+import { createNode } from '@deskforge/core'
+
+function Text(value: string, props: Record<string, unknown> = {}) {
+  return createNode('text', {
+    text: value,
+    ...props,
+  })
+}
+
+function View(props: Record<string, unknown> = {}, children: any[] = []) {
+  return createNode('view', props, children)
+}
+```
+
+This pattern keeps your app code readable while staying close to the underlying node tree model.
+
+---
+
+## 8. Styling and layout
+
+The current implementation uses inline style objects and passes them through as node props. A simple screen might look like this:
+
+```ts
+const card = createNode('view', {
+  style: {
+    background: '#ffffff',
+    borderRadius: 24,
+    padding: 24,
+    boxShadow: '0 10px 20px rgba(0,0,0,0.08)',
+  },
+}, [
+  createNode('text', { text: 'Card title', font: '700 24px sans-serif' }),
+])
+```
+
+### Best practices
+
+- keep styles in a single place when the app grows
+- use small helper components for repeated layout patterns
+- keep screen logic separate from presentation
+- treat each screen as a pure function that returns a node tree
+
+---
+
+## 9. Rendering pipeline
+
+DeskForge follows a straightforward pipeline:
+
+```text
+Screen function -> Node tree -> Renderer -> PNG / buffer / output
+```
+
+### What happens internally
+
+1. A screen returns a node tree.
+2. The node tree is composed of parent and child nodes.
+3. The renderer visits each node.
+4. The renderer converts node props into drawing commands.
+5. The output is saved or displayed.
+
+This makes it easy to reason about your app as a tree of visual elements.
+
+---
+
+## 10. How to structure a real project
+
+A practical project structure may look like this:
+
+```text
+my-app/
+  package.json
+  tsconfig.json
+  src/
+    App.ts
+    screens/
+      Home.ts
+      Details.ts
+      Settings.ts
+    ui/
+      Responsive.ts
+      components/
+        Card.ts
+        Button.ts
+```
+
+### Suggested workflow
+
+1. Create a main `App.ts` file.
+2. Create one file per screen.
+3. Create helper modules for common UI primitives.
+4. Register routes in one place.
+5. Render the current screen through the renderer.
+
+---
+
+## 11. Extending DeskForge
+
+The framework is modular, so you can extend it in several ways:
+
+### Add custom components
+
+Create a new node type and teach the renderer how to paint it. This is the most direct way to introduce custom visuals.
+
+### Add custom painters
+
+The renderer package supports custom painters. If you need a new visual primitive, register a painter for it.
+
+### Add new packages
+
+The monorepo already includes packages for state, theme, device support, notifications, and more. You can build on those modules to grow the framework into a bigger app platform.
+
+---
+
+## 12. Building a complete app example
+
+Here is a complete example that follows the patterns already used in the repository.
+
+```ts
+import * as fs from 'fs'
+import { Renderer } from '@deskforge/renderer'
+import { Router, Screen } from '@deskforge/router'
+import { Text, View, Window } from './src/ui/Responsive'
+
+Router({
+  home: () => Screen({ style: { background: '#f8fafc', padding: 24 } })
+    .add(
+      View({ style: { background: '#ffffff', borderRadius: 24, padding: 24 } }),
+      Text('DeskForge App', { style: { fontSize: 24, fontWeight: '700' } }),
+      Text('This is a simple DeskForge screen.', { style: { color: '#4b5563', fontSize: 16 } }),
+    )
+    .build(),
+})
+
+function createRoot() {
+  return Window({ style: { background: '#f7f8fb', padding: 24 } })
+    .add(
+      View({ style: { background: '#ffffff', borderRadius: 32, padding: 24 } }),
+      Text('My App Shell', { style: { fontSize: 24, fontWeight: '700' } }),
+      Router.render() ?? Text('No screen selected.', { style: { color: '#6b7280', fontSize: 16 } }),
+    )
+    .build()
+}
+
+async function main() {
+  fs.mkdirSync('./dist', { recursive: true })
+
+  const renderer = new Renderer({
+    width: 900,
+    height: 700,
+    backgroundColor: '#f7f8fb',
+  })
+
+  Router.go('home')
+  renderer.renderNode(createRoot())
+  await renderer.saveAs('./dist/demo.png')
+}
+
+main().catch(console.error)
+```
+
+---
+
+## 13. Tips and best practices
+
+- Keep screens focused on one responsibility.
+- Compose small building blocks instead of writing large monolithic screens.
+- Use helper functions to hide repetitive node creation.
+- Keep route names stable and descriptive.
+- Keep rendering logic separate from navigation logic.
+- Use `dist/` for generated assets so your source stays clean.
+
+---
+
+## 14. Current limitations and roadmap
+
+The current repository is a solid foundation, but it is still early-stage. Some areas are intentionally simple and may evolve over time:
+
+- the renderer is focused on practical visual output
+- the router is lightweight and screen-based
+- custom components and advanced layout systems are still being expanded
+- additional package features may be added as the framework grows
+
+That said, the architecture is already good enough for building small, structured apps and rendering them in a controlled pipeline.
+
+---
+
+## 15. Summary
+
+DeskForge is best understood as a small, modular framework for building UI trees and rendering them as visual output. The core workflow is:
+
+1. define a node tree
+2. compose screens
+3. register routes
+4. render the active screen
+5. export the result
+
+If you follow the structure used by the example app, you can build a simple and maintainable app very quickly.
+
+---
+
+## 16. Next steps
+
+To continue learning the framework:
+
+- read the example app in `examples/deskforge-app`
+- inspect the core packages in `packages/core`, `packages/router`, and `packages/renderer`
+- start with a single screen and build outward from there
+- add custom helpers for text, cards, buttons, and layouts as your app grows

package/examples/deskforge-app/App.ts

@@ -0,0 +1,50 @@
+import * as fs from 'fs'
+import { Renderer } from '@deskforge/renderer'
+import { createApp, ManifestBuilder } from '@deskforge/router'
+import { HomeRoute, DetailsRoute } from './src/screens'
+import { Text, View, Window } from './src/ui/Responsive'
+
+// Define routes using the manifest builder (Expo Router style).
+const routes = new ManifestBuilder()
+  .add('index.ts', HomeRoute.component)
+  .add('details.ts', DetailsRoute.component)
+  .build()
+
+const { router } = createApp({ manifest: routes })
+
+function createRoot() {
+  return Window({ style: { background: '#f7f8fb', padding: 24 } })
+    .add(
+      View({ style: { background: '#ffffff', borderRadius: 32, padding: 24 } }),
+      Text('DeskForge App Example', { style: { fontSize: 24, fontWeight: '700' } }),
+      router.render() ?? Text('No screen selected.', { style: { color: '#6b7280', fontSize: 16 } }),
+    )
+    .build()
+}
+
+async function main() {
+  fs.mkdirSync('./dist', { recursive: true })
+
+  const renderer = new Renderer({
+    width: 800,
+    height: 600,
+    backgroundColor: '#f7f8fb',
+  })
+
+  // Navigate to home and render
+  router.navigate('/')
+  renderer.renderNode(createRoot())
+  await renderer.saveAs('./dist/deskforge-app-home.png')
+  console.log('Rendered home screen to dist/deskforge-app-home.png')
+
+  // Navigate to details and render
+  router.navigate('/details')
+  renderer.renderNode(createRoot())
+  await renderer.saveAs('./dist/deskforge-app-details.png')
+  console.log('Rendered details screen to dist/deskforge-app-details.png')
+}
+
+main().catch(err => {
+  console.error(err)
+  process.exit(1)
+})

package/examples/deskforge-app/README.md

@@ -0,0 +1,80 @@
+# DeskForge Expo-style App Example
+
+This example demonstrates a screen-based app structure using file-based routing similar to Expo Router and Next.js.
+
+## File structure
+
+The app uses a folder structure where each file becomes a route automatically:
+
+```
+app/
+  index.ts         → / (home route)
+  details.ts       → /details
+  note/
+    [id].ts        → /note/:id (dynamic route)
+```
+
+## Example layout
+
+```
+examples/deskforge-app/
+  App.ts                 # entry point with router setup
+  src/
+    screens/
+      Home.ts            # / route
+      Details.ts         # /details route
+      index.ts           # exports
+    ui/
+      Responsive.ts      # helper components
+  package.json
+  tsconfig.json
+```
+
+## Routing model
+
+Unlike the older explicit `Router({ home: ..., details: ... })` API, the new file-based router works like Expo Router:
+
+- file paths map to URL routes
+- `/index.ts` → `/`
+- `/about.ts` → `/about`
+- `/note/[id].ts` → `/note/:id`
+- nested folders create nested routes
+
+## Usage
+
+```bash
+cd examples/deskforge-app
+npm install
+npm run build
+npm run start
+```
+
+This renders images for both screens into the `dist` folder.
+
+## Adding a new route
+
+1. Create a new file in `src/screens/`:
+   ```ts
+   // src/screens/Settings.ts
+   import { Screen, Text, View } from '../ui/Responsive'
+
+   export default function SettingsScreen(params) {
+     return Screen()
+       .add(Text('Settings'), Text('Coming soon...'))
+       .build()
+   }
+   ```
+
+2. Add it to the manifest in `App.ts`:
+   ```ts
+   const routes = new ManifestBuilder()
+     .add('index.ts', HomeScreen)
+     .add('details.ts', DetailsScreen)
+     .add('settings.ts', SettingsScreen)  // new route
+     .build()
+   ```
+
+3. Navigate to it:
+   ```ts
+   router.navigate('/settings')
+   ```

package/examples/deskforge-app/app.json

@@ -0,0 +1,10 @@
+{
+  "expo": {
+    "name": "DeskForgeApp",
+    "slug": "deskforge-app",
+    "version": "1.0.0",
+    "entryPoint": "./App.ts",
+    "assetBundlePatterns": ["**/*"],
+    "platforms": ["ios", "android", "web"]
+  }
+}

package/examples/deskforge-app/dist/App.d.ts

@@ -0,0 +1 @@
+export {};