Skip to content

Latest commit

 

History

History
145 lines (100 loc) · 4.11 KB

README.md

File metadata and controls

145 lines (100 loc) · 4.11 KB

📘 PishPosh – Visual Programming via Subway Maps

PishPosh is a lightweight, pure-DOM visual programming environment with modular plugin architecture. Users build “programs” by placing stations (nodes) and connecting them (edges). It uses reactive signals and event-driven agents for computation and data flow.

🔗 Overview

SubwayBuilder (Web Component)
 └─ Application (core)
      ├─ GridPlugin
      ├─ ToolboxPlugin
      ├─ PanZoomPlugin
      ├─ StationPlugin
      ├─ ConnectPlugin
      ├─ ConnectionLinePlugin
      ├─ MoveStationPlugin
      ├─ AgentLibraryPlugin
      ├─ AgentsPlugin
      ├─ AgentChooserPlugin
      └─ PropertiesPanelPlugin

Each plugin adds one cohesive feature — from visuals and interaction to agents and metadata — allowing for clean, feature-by-feature extension.

🚂 Application Core

  • Application.js sets up the main SVG canvas (<svg id="svg-canvas">) and provides:

    • use(plugin): loads a plugin
    • init(): initializes all plugins
    • graph: instance of reactive Graph (nodes & connections)
    • Event bus with on(event, handler) and emit(event, data)

🛤️ Core Plugins

  1. GridPlugin

    • Renders a tile-based grid behind everything
    • Updates automatically when panning/zooming happens

  2. ToolboxPlugin

    • Renders a floating toolbar with tool icons
    • Emits toolSelected when user switches between select / station / connect modes

  3. PanZoomPlugin

    • Enables click-drag panning and wheel zooming of the SVG viewBox
    • Emits viewBoxChanged to trigger grid redraw

  4. StationPlugin

    • Handles creating stations (nodes) when in station-mode
    • Renders circles and labels and hooks them into the reactive graph

  5. ConnectPlugin

    • Enables “connecting” mode:

      • Press down on a station, drag to another, then release to create a connection

    • Draws a temporary line during interaction

  6. ConnectionLinePlugin

    • Listens on connectionAdded/Removed
    • Renders permanent lines and labels, reacts to station moves
    • Follows a similar reactive pattern to StationPlugin

  7. MoveStationPlugin

    • Moves existing stations by dragging in select mode
    • Snaps movement to the grid

🤖 Agent Plugins (Programmatic Magic)

  1. AgentLibraryPlugin

    • Registers agent types (e.g., TimerAgent, GraphAgent)
    • Agents are small event-driven objects that can send, receive, and emit data

  2. AgentsPlugin

    • Instantiates agents for each node or connection using Graph metadata
    • Routes agent I/O via the application event bus (agentCreated, agentOutput, etc.)

  3. AgentChooserPlugin

  • Renders a draggable palette of available agent types
  • Drag an agent type onto the map to create a new node with that agent attached
  1. PropertiesPanelPlugin
  • Displays selected station/connection properties (position, label, agent)
  • Supports live editing

🧩 How to Use

1. Installation

npm install pishposh
# or clone the repo:
git clone https://github.com/catpea/pishposh.git

2. Add to your HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <subway-builder></subway-builder>
    <script type="module" src="./SubwayBuilder.js"></script>
  </body>
</html>

3. Interact!

  • 🛠 Switch tools via the toolbar
  • ⚪ Click in station mode to add nodes
  • 📏 Drag in select mode to pan or move nodes
  • 🔗 In connect mode, drag from one station to another
  • 🧪 Use the Agents panel to assign agents (e.g., TimerAgent, GraphAgent)
  • ✍️ Inspect and edit station/connection properties in the Properties panel

📚 Why It Matters

  • Modular structure: combine only what you need
  • Pure DOM + SVG: no dependencies, full control
  • Reactive & event-driven: clear flow of data between UI and agents
  • Self-hosted computing: nodes can introspect or mutate the graph itself (via GraphAgent)
  • Great starter/project learning: accessible, extendable, and fun to hack