@zseven-w/pen-types 0.0.1

package/README.md

@@ -0,0 +1,31 @@
+# @zseven-w/pen-types
+
+Type definitions for the [OpenPencil](https://github.com/nicepkg/openpencil) document model.
+
+## Install
+
+```bash
+npm install @zseven-w/pen-types
+```
+
+## What's Included
+
+This package provides all TypeScript types and interfaces for the OpenPencil design file format (`.op`):
+
+- **Document model** — `PenDocument`, `PenPage`, `PenNode` and all node types (`FrameNode`, `RectangleNode`, `EllipseNode`, `TextNode`, `ImageNode`, `PathNode`, etc.)
+- **Styles** — `PenFill` (solid, gradient, image), `PenStroke`, `PenEffect` (blur, shadow), `BlendMode`, `StyledTextSegment`
+- **Variables & Themes** — `VariableDefinition`, `VariableValue`, `ThemedValue`
+- **Canvas state** — `ToolType`, `ViewportState`, `SelectionState`, `CanvasInteraction`
+- **UIKit** — `UIKit`, `KitComponent`, `ComponentCategory`
+- **Theme presets** — `ThemePreset`, `ThemePresetFile`
+- **Design spec** — `DesignMdSpec`, `DesignMdColor`, `DesignMdTypography`
+
+## Usage
+
+```ts
+import type { PenDocument, PenNode, FrameNode } from '@zseven-w/pen-types'
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@zseven-w/pen-types",
+  "version": "0.0.1",
+  "description": "Type definitions for OpenPencil document model",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/src/canvas.ts

@@ -0,0 +1,31 @@
+export type ToolType =
+  | 'select'
+  | 'frame'
+  | 'rectangle'
+  | 'ellipse'
+  | 'line'
+  | 'polygon'
+  | 'path'
+  | 'text'
+  | 'hand'
+
+export interface ViewportState {
+  zoom: number
+  panX: number
+  panY: number
+}
+
+export interface SelectionState {
+  selectedIds: string[]
+  activeId: string | null
+  hoveredId: string | null
+  enteredFrameId: string | null
+  enteredFrameStack: string[]
+}
+
+export interface CanvasInteraction {
+  isDrawing: boolean
+  isPanning: boolean
+  isDragging: boolean
+  drawStartPoint: { x: number; y: number } | null
+}

package/src/design-md.ts

@@ -0,0 +1,24 @@
+export interface DesignMdSpec {
+  /** Original markdown source (for round-trip fidelity) */
+  raw: string
+  projectName?: string
+  visualTheme?: string
+  colorPalette?: DesignMdColor[]
+  typography?: DesignMdTypography
+  componentStyles?: string
+  layoutPrinciples?: string
+  generationNotes?: string
+}
+
+export interface DesignMdColor {
+  name: string
+  hex: string
+  role: string
+}
+
+export interface DesignMdTypography {
+  fontFamily?: string
+  headings?: string
+  body?: string
+  scale?: string
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+// Styles
+export type {
+  BlendMode,
+  SolidFill,
+  GradientStop,
+  LinearGradientFill,
+  RadialGradientFill,
+  ImageFill,
+  PenFill,
+  PenStroke,
+  BlurEffect,
+  ShadowEffect,
+  PenEffect,
+  StyledTextSegment,
+} from './styles.js'
+
+// Variables
+export type {
+  VariableDefinition,
+  VariableValue,
+  ThemedValue,
+} from './variables.js'
+
+// Canvas
+export type {
+  ToolType,
+  ViewportState,
+  SelectionState,
+  CanvasInteraction,
+} from './canvas.js'
+
+// Document model
+export type {
+  PenPage,
+  PenDocument,
+  PenNodeType,
+  SizingBehavior,
+  PenNodeBase,
+  ContainerProps,
+  FrameNode,
+  GroupNode,
+  RectangleNode,
+  EllipseNode,
+  LineNode,
+  PolygonNode,
+  PathNode,
+  TextNode,
+  ImageFitMode,
+  ImageNode,
+  IconFontNode,
+  RefNode,
+  PenNode,
+} from './pen.js'
+
+// UIKit
+export type {
+  ComponentCategory,
+  KitComponent,
+  UIKit,
+} from './uikit.js'
+
+// Theme presets
+export type {
+  ThemePreset,
+  ThemePresetFile,
+} from './theme-preset.js'
+
+// Design.md
+export type {
+  DesignMdSpec,
+  DesignMdColor,
+  DesignMdTypography,
+} from './design-md.js'

package/src/pen.ts

@@ -0,0 +1,221 @@
+import type {
+  PenFill,
+  PenStroke,
+  PenEffect,
+  StyledTextSegment,
+} from './styles.js'
+import type { VariableDefinition } from './variables.js'
+
+// --- Page ---
+
+export interface PenPage {
+  id: string
+  name: string
+  children: PenNode[]
+}
+
+// --- Document Root ---
+
+export interface PenDocument {
+  version: string
+  name?: string
+  themes?: Record<string, string[]>
+  variables?: Record<string, VariableDefinition>
+  pages?: PenPage[]
+  children: PenNode[]
+}
+
+// --- Node Types ---
+
+export type PenNodeType =
+  | 'frame'
+  | 'group'
+  | 'rectangle'
+  | 'ellipse'
+  | 'line'
+  | 'polygon'
+  | 'path'
+  | 'text'
+  | 'image'
+  | 'icon_font'
+  | 'ref'
+
+export type SizingBehavior = number | 'fit_content' | 'fill_container' | string
+
+// --- Base ---
+
+export interface PenNodeBase {
+  id: string
+  type: PenNodeType
+  name?: string
+  role?: string // semantic role for AI generation ("button", "card", "heading", etc.)
+  x?: number
+  y?: number
+  rotation?: number
+  opacity?: number | string // number or $variable
+  enabled?: boolean | string
+  visible?: boolean // default true
+  locked?: boolean // default false
+  flipX?: boolean
+  flipY?: boolean
+  theme?: Record<string, string>
+}
+
+// --- Container (shared layout props) ---
+
+export interface ContainerProps {
+  width?: SizingBehavior
+  height?: SizingBehavior
+  layout?: 'none' | 'vertical' | 'horizontal'
+  gap?: number | string
+  padding?:
+    | number
+    | [number, number]
+    | [number, number, number, number]
+    | string
+  justifyContent?:
+    | 'start'
+    | 'center'
+    | 'end'
+    | 'space_between'
+    | 'space_around'
+  alignItems?: 'start' | 'center' | 'end'
+  clipContent?: boolean
+  children?: PenNode[]
+  cornerRadius?: number | [number, number, number, number]
+  fill?: PenFill[]
+  stroke?: PenStroke
+  effects?: PenEffect[]
+}
+
+// --- Concrete Nodes ---
+
+export interface FrameNode extends PenNodeBase, ContainerProps {
+  type: 'frame'
+  reusable?: boolean
+  slot?: string[]
+}
+
+export interface GroupNode extends PenNodeBase, ContainerProps {
+  type: 'group'
+}
+
+export interface RectangleNode extends PenNodeBase, ContainerProps {
+  type: 'rectangle'
+}
+
+export interface EllipseNode extends PenNodeBase {
+  type: 'ellipse'
+  width?: SizingBehavior
+  height?: SizingBehavior
+  cornerRadius?: number
+  innerRadius?: number
+  startAngle?: number
+  sweepAngle?: number
+  fill?: PenFill[]
+  stroke?: PenStroke
+  effects?: PenEffect[]
+}
+
+export interface LineNode extends PenNodeBase {
+  type: 'line'
+  x2?: number
+  y2?: number
+  stroke?: PenStroke
+  effects?: PenEffect[]
+}
+
+export interface PolygonNode extends PenNodeBase {
+  type: 'polygon'
+  polygonCount: number
+  width?: SizingBehavior
+  height?: SizingBehavior
+  cornerRadius?: number
+  fill?: PenFill[]
+  stroke?: PenStroke
+  effects?: PenEffect[]
+}
+
+export interface PathNode extends PenNodeBase {
+  type: 'path'
+  iconId?: string // Iconify icon ID, e.g. "lucide:home"
+  d: string
+  width?: SizingBehavior
+  height?: SizingBehavior
+  fill?: PenFill[]
+  stroke?: PenStroke
+  effects?: PenEffect[]
+}
+
+export interface TextNode extends PenNodeBase {
+  type: 'text'
+  width?: SizingBehavior
+  height?: SizingBehavior
+  content: string | StyledTextSegment[]
+  fontFamily?: string
+  fontSize?: number
+  fontWeight?: number | string
+  fontStyle?: 'normal' | 'italic'
+  letterSpacing?: number
+  lineHeight?: number
+  textAlign?: 'left' | 'center' | 'right' | 'justify'
+  textAlignVertical?: 'top' | 'middle' | 'bottom'
+  textGrowth?: 'auto' | 'fixed-width' | 'fixed-width-height'
+  underline?: boolean
+  strikethrough?: boolean
+  fill?: PenFill[]
+  effects?: PenEffect[]
+}
+
+export type ImageFitMode = 'fill' | 'fit' | 'crop' | 'tile'
+
+export interface ImageNode extends PenNodeBase {
+  type: 'image'
+  src: string
+  objectFit?: ImageFitMode
+  width?: SizingBehavior
+  height?: SizingBehavior
+  cornerRadius?: number | [number, number, number, number]
+  effects?: PenEffect[]
+  exposure?: number    // -100 to 100
+  contrast?: number    // -100 to 100
+  saturation?: number  // -100 to 100
+  temperature?: number // -100 to 100
+  tint?: number        // -100 to 100
+  highlights?: number  // -100 to 100
+  shadows?: number     // -100 to 100
+  imagePrompt?: string       // Descriptive prompt for AI image generation (long)
+  imageSearchQuery?: string  // Short keywords for image search (e.g. "burger fries")
+}
+
+export interface IconFontNode extends PenNodeBase {
+  type: 'icon_font'
+  iconFontName: string
+  iconFontFamily?: string
+  width?: SizingBehavior
+  height?: SizingBehavior
+  fill?: PenFill[]
+  stroke?: PenStroke
+}
+
+export interface RefNode extends PenNodeBase {
+  type: 'ref'
+  ref: string
+  descendants?: Record<string, Partial<PenNode>>
+  children?: PenNode[]
+}
+
+// --- Union ---
+
+export type PenNode =
+  | FrameNode
+  | GroupNode
+  | RectangleNode
+  | EllipseNode
+  | LineNode
+  | PolygonNode
+  | PathNode
+  | TextNode
+  | ImageNode
+  | IconFontNode
+  | RefNode

package/src/styles.ts

@@ -0,0 +1,108 @@
+export type BlendMode =
+  | 'normal'
+  | 'darken'
+  | 'multiply'
+  | 'screen'
+  | 'overlay'
+  | 'lighten'
+  | 'difference'
+  | 'hue'
+  | 'saturation'
+  | 'color'
+  | 'luminosity'
+
+// --- Fill Types ---
+
+export interface SolidFill {
+  type: 'solid'
+  color: string // #RRGGBB or #RRGGBBAA
+  opacity?: number
+  blendMode?: BlendMode
+}
+
+export interface GradientStop {
+  offset: number // 0 to 1
+  color: string
+}
+
+export interface LinearGradientFill {
+  type: 'linear_gradient'
+  angle?: number
+  stops: GradientStop[]
+  opacity?: number
+  blendMode?: BlendMode
+}
+
+export interface RadialGradientFill {
+  type: 'radial_gradient'
+  cx?: number
+  cy?: number
+  radius?: number
+  stops: GradientStop[]
+  opacity?: number
+  blendMode?: BlendMode
+}
+
+export interface ImageFill {
+  type: 'image'
+  url: string
+  mode?: 'fill' | 'fit' | 'crop' | 'tile' | 'stretch'
+  opacity?: number
+  exposure?: number    // -100 to 100
+  contrast?: number    // -100 to 100
+  saturation?: number  // -100 to 100
+  temperature?: number // -100 to 100
+  tint?: number        // -100 to 100
+  highlights?: number  // -100 to 100
+  shadows?: number     // -100 to 100
+}
+
+export type PenFill =
+  | SolidFill
+  | LinearGradientFill
+  | RadialGradientFill
+  | ImageFill
+
+// --- Stroke ---
+
+export interface PenStroke {
+  thickness: number | [number, number, number, number]
+  align?: 'inside' | 'center' | 'outside'
+  join?: 'miter' | 'bevel' | 'round'
+  cap?: 'none' | 'round' | 'square'
+  dashPattern?: number[]
+  fill?: PenFill[]
+}
+
+// --- Effects ---
+
+export interface BlurEffect {
+  type: 'blur' | 'background_blur'
+  radius: number
+}
+
+export interface ShadowEffect {
+  type: 'shadow'
+  inner?: boolean
+  offsetX: number
+  offsetY: number
+  blur: number
+  spread: number
+  color: string
+}
+
+export type PenEffect = BlurEffect | ShadowEffect
+
+// --- Text ---
+
+export interface StyledTextSegment {
+  text: string
+  fontFamily?: string
+  fontSize?: number
+  fontWeight?: number
+  fontStyle?: 'normal' | 'italic'
+  fill?: string
+  underline?: boolean
+  strikethrough?: boolean
+  href?: string
+}

package/src/theme-preset.ts

@@ -0,0 +1,17 @@
+import type { VariableDefinition } from './variables.js'
+
+export interface ThemePreset {
+  id: string
+  name: string
+  themes: Record<string, string[]>
+  variables: Record<string, VariableDefinition>
+  createdAt: number
+}
+
+export interface ThemePresetFile {
+  type: 'openpencil-theme-preset'
+  version: '1.0.0'
+  name: string
+  themes: Record<string, string[]>
+  variables: Record<string, VariableDefinition>
+}

package/src/uikit.ts

@@ -0,0 +1,42 @@
+import type { PenDocument } from './pen.js'
+
+export type ComponentCategory =
+  | 'buttons'
+  | 'inputs'
+  | 'cards'
+  | 'navigation'
+  | 'layout'
+  | 'feedback'
+  | 'data-display'
+  | 'other'
+
+export interface KitComponent {
+  /** Node ID of the reusable FrameNode in the kit document */
+  id: string
+  /** Display name */
+  name: string
+  /** Category for organization in the browser */
+  category: ComponentCategory
+  /** Tags for search */
+  tags: string[]
+  /** Component dimensions for preview sizing */
+  width: number
+  height: number
+}
+
+export interface UIKit {
+  /** Unique identifier */
+  id: string
+  /** Display name */
+  name: string
+  /** Optional description */
+  description?: string
+  /** Version string */
+  version: string
+  /** Whether this is a built-in kit that ships with the app */
+  builtIn: boolean
+  /** Backing PenDocument containing the reusable nodes */
+  document: PenDocument
+  /** Extracted component metadata for browsing */
+  components: KitComponent[]
+}

package/src/variables.ts

@@ -0,0 +1,11 @@
+export interface VariableDefinition {
+  type: 'color' | 'number' | 'boolean' | 'string'
+  value: VariableValue
+}
+
+export type VariableValue = string | number | boolean | ThemedValue[]
+
+export interface ThemedValue {
+  value: string | number | boolean
+  theme?: Record<string, string>
+}