pywire 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

pywire/client/src/core/app.ts

@@ -0,0 +1,263 @@
+import { TransportManager, TransportConfig } from './transport-manager'
+import { DOMUpdater } from './dom-updater'
+import { ServerMessage, ClientMessage, EventData, RelocateMessage } from './transports'
+import { UnifiedEventHandler } from '../events/handler'
+
+export interface PyWireConfig extends TransportConfig {
+  /** Auto-initialize on DOMContentLoaded */
+  autoInit?: boolean
+  /** Enable verbose debug logging */
+  debug?: boolean
+}
+
+const DEFAULT_CONFIG: PyWireConfig = {
+  autoInit: true,
+  enableWebTransport: true,
+  enableWebSocket: true,
+  enableHTTP: true,
+  debug: false,
+}
+
+/**
+ * Core PyWire Application class.
+ * Provides transport, DOM updates, SPA navigation, and event handling.
+ * Dev-only features (status overlay, error traces) are in the dev bundle.
+ */
+export class PyWireApp {
+  protected transport: TransportManager
+  protected updater: DOMUpdater
+  protected eventHandler: UnifiedEventHandler
+  protected initialized = false
+  protected config: PyWireConfig
+  protected siblingPaths: string[] = []
+  protected pathRegexes: RegExp[] = []
+  protected pjaxEnabled = false
+  protected isConnected = false
+
+  constructor(config: Partial<PyWireConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.transport = new TransportManager(this.config)
+    this.updater = new DOMUpdater(this.config.debug)
+    this.eventHandler = new UnifiedEventHandler(this)
+  }
+
+  getConfig(): PyWireConfig {
+    return this.config
+  }
+
+  /**
+   * Initialize the PyWire application.
+   */
+  async init(): Promise<void> {
+    if (this.initialized) return
+    this.initialized = true
+
+    // Setup message handling
+    this.transport.onMessage((msg) => this.handleMessage(msg))
+    this.transport.onStatusChange((connected) => this.handleStatusChange(connected))
+
+    // Connect transport with fallback
+    try {
+      await this.transport.connect()
+    } catch (e) {
+      console.error('PyWire: Failed to connect:', e)
+    }
+
+    // Load SPA metadata and setup navigation
+    this.loadSPAMetadata()
+    this.setupSPANavigation()
+
+    // Setup event interception via UnifiedEventHandler
+    this.eventHandler.init()
+
+    console.log(
+      `PyWire: Initialized (transport: ${this.transport.getActiveTransport()}, spa_paths: ${this.siblingPaths.length}, pjax: ${this.pjaxEnabled})`
+    )
+  }
+
+  /**
+   * Handle connection status changes. Override in dev bundle for UI.
+   */
+  protected handleStatusChange(connected: boolean): void {
+    this.isConnected = connected
+    // Base implementation: no UI, just track state
+  }
+
+  /**
+   * Load SPA navigation metadata from injected script tag.
+   */
+  protected loadSPAMetadata(): void {
+    const metaScript = document.getElementById('_pywire_spa_meta')
+    if (metaScript) {
+      try {
+        const meta = JSON.parse(metaScript.textContent || '{}')
+        this.siblingPaths = meta.sibling_paths || []
+        this.pjaxEnabled = !!meta.enable_pjax
+        if (meta.debug !== undefined) {
+          this.config.debug = !!meta.debug
+        }
+        // Convert path patterns to regexes for matching
+        this.pathRegexes = this.siblingPaths.map((p) => this.patternToRegex(p))
+      } catch (e) {
+        console.warn('PyWire: Failed to parse SPA metadata', e)
+      }
+    }
+  }
+
+  /**
+   * Convert route pattern like '/a/:id' to regex.
+   */
+  protected patternToRegex(pattern: string): RegExp {
+    // Escape special regex chars except for our placeholders
+    let regex = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    // Replace :param:type or :param with capture groups
+    regex = regex.replace(/:(\\w+)(:\\w+)?/g, '([^/]+)')
+    // Replace {param:type} or {param} with capture groups
+    regex = regex.replace(/\\{(\\w+)(:\\w+)?\\}/g, '([^/]+)')
+    return new RegExp(`^${regex}$`)
+  }
+
+  /**
+   * Check if a path matches any sibling path pattern.
+   */
+  protected isSiblingPath(path: string): boolean {
+    return this.pathRegexes.some((regex) => regex.test(path))
+  }
+
+  /**
+   * Setup SPA navigation for sibling paths.
+   */
+  protected setupSPANavigation(): void {
+    // Handle browser back/forward
+    window.addEventListener('popstate', () => {
+      this.sendRelocate(window.location.pathname + window.location.search)
+    })
+
+    if (this.siblingPaths.length === 0 && !this.pjaxEnabled) return
+
+    // Intercept link clicks
+    document.addEventListener('click', (e) => {
+      const link = (e.target as Element).closest('a[href]') as HTMLAnchorElement | null
+      if (!link) return
+
+      // Only intercept same-origin links
+      if (link.origin !== window.location.origin) return
+
+      // Ignore special links
+      if (link.hasAttribute('download') || link.target === '_blank') return
+
+      // Check if matches criteria
+      let shouldIntercept = false
+
+      if (this.pjaxEnabled) {
+        shouldIntercept = true
+      } else if (this.isSiblingPath(link.pathname)) {
+        shouldIntercept = true
+      }
+
+      if (shouldIntercept) {
+        e.preventDefault()
+        this.navigateTo(link.pathname + link.search)
+      }
+    })
+  }
+
+  /**
+   * Navigate to a path using SPA navigation.
+   */
+  navigateTo(path: string): void {
+    if (!this.isConnected) {
+      console.warn('PyWire: Navigation blocked - Offline')
+      return
+    }
+
+    history.pushState({}, '', path)
+    this.sendRelocate(path)
+  }
+
+  /**
+   * Send relocate message to server.
+   */
+  protected sendRelocate(path: string): void {
+    const message: RelocateMessage = {
+      type: 'relocate',
+      path,
+    }
+    this.transport.send(message)
+  }
+
+  /**
+   * Send an event to the server.
+   */
+  sendEvent(handler: string, data: EventData): void {
+    const message: ClientMessage = {
+      type: 'event',
+      handler,
+      path: window.location.pathname + window.location.search,
+      data,
+    }
+    this.transport.send(message)
+  }
+
+  /**
+   * Handle incoming server message. Override in dev bundle for error_trace.
+   */
+  protected async handleMessage(msg: ServerMessage): Promise<void> {
+    switch (msg.type) {
+      case 'update':
+        if (msg.regions && msg.regions.length > 0) {
+          msg.regions.forEach((update) => {
+            this.updater.updateRegion(update.region, update.html)
+          })
+        } else if (msg.html) {
+          this.updater.update(msg.html)
+        }
+        break
+
+      case 'reload':
+        console.log('PyWire: Reloading...')
+        window.location.reload()
+        break
+
+      case 'error':
+        console.error('PyWire: Server error:', msg.error)
+        break
+
+      case 'error_trace':
+        // In core bundle, just log the error (no source loading)
+        console.error('PyWire: Error:', msg.error)
+        break
+
+      case 'console':
+        if (msg.lines && msg.lines.length > 0) {
+          const prefix = 'PyWire Server:'
+          const joined = msg.lines.join('\n')
+          if (msg.level === 'error') {
+            console.error(prefix, joined)
+          } else if (msg.level === 'warn') {
+            console.warn(prefix, joined)
+          } else {
+            console.log(prefix, joined)
+          }
+        }
+        break
+
+      default:
+        console.warn('PyWire: Unknown message type', msg)
+    }
+  }
+
+  /**
+   * Get the current transport name.
+   */
+  getTransport(): string | null {
+    return this.transport.getActiveTransport()
+  }
+
+  /**
+   * Disconnect from the server.
+   */
+  disconnect(): void {
+    this.transport.disconnect()
+  }
+}

pywire/client/src/core/dom-updater.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { DOMUpdater } from './dom-updater'
+import morphdom from 'morphdom'
+
+vi.mock('morphdom', () => ({
+  default: vi.fn((_from, _to, _options) => {
+    // Basic simulation of morphdom: just replace content if no options,
+    // or call hooks if provided (we only care about onBeforeElUpdated)
+    return
+  }),
+}))
+
+describe('DOMUpdater', () => {
+  let updater: DOMUpdater
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    updater = new DOMUpdater()
+    document.documentElement.innerHTML = '<body><div id="app"></div></body>'
+  })
+
+  it('should call morphdom with custom options', () => {
+    updater.update('<html><body><div id="app">New</div></body></html>')
+    expect(morphdom).toHaveBeenCalledWith(
+      expect.any(Node),
+      expect.stringContaining('New'),
+      expect.objectContaining({
+        onBeforeElUpdated: expect.any(Function),
+      })
+    )
+  })
+
+  it('should preserve input value if focused and similar', () => {
+    const morphdomMock = vi.mocked(morphdom)
+    updater.update('<html><body><input id="test" value="server"></body></html>')
+
+    // Get the onBeforeElUpdated hook
+    const options = morphdomMock.mock.calls[0][2]
+    const onBeforeElUpdated = options?.onBeforeElUpdated
+
+    if (!onBeforeElUpdated) throw new Error('Hook not found')
+
+    const fromEl = document.createElement('input')
+    fromEl.value = 'server-ahead'
+    vi.spyOn(document, 'activeElement', 'get').mockReturnValue(fromEl)
+
+    const toEl = document.createElement('input')
+    toEl.setAttribute('value', 'server')
+
+    const result = onBeforeElUpdated(fromEl, toEl)
+
+    expect(result).toBe(true)
+    expect(toEl.value).toBe('server-ahead')
+  })
+
+  it('should NOT preserve input value if completely different', () => {
+    const morphdomMock = vi.mocked(morphdom)
+    updater.update('<html><body><input id="test" value="server"></body></html>')
+
+    const options = morphdomMock.mock.calls[0][2]
+    const onBeforeElUpdated = options?.onBeforeElUpdated
+
+    if (!onBeforeElUpdated) throw new Error('Hook not found')
+
+    const fromEl = document.createElement('input')
+    fromEl.value = 'user-typed-something-else'
+    vi.spyOn(document, 'activeElement', 'get').mockReturnValue(fromEl)
+
+    const toEl = document.createElement('input')
+    toEl.setAttribute('value', 'server-new')
+    toEl.value = 'server-new'
+
+    onBeforeElUpdated(fromEl, toEl)
+
+    // Should NOT have overwritten toEl.value with fromEl.value because they don't start with each other
+    expect(toEl.value).toBe('server-new')
+  })
+})

pywire/client/src/core/dom-updater.ts

@@ -0,0 +1,321 @@
+/**
+ * DOM Updater using morphdom for efficient DOM diffing.
+ */
+import morphdom from 'morphdom'
+
+interface FocusState {
+  /** CSS selector to find the element */
+  selector: string
+  /** Element ID if available */
+  id: string | null
+  tagName: string
+  selectionStart: number | null
+  selectionEnd: number | null
+  scrollTop: number
+  scrollLeft: number
+  value: string
+}
+
+export class DOMUpdater {
+  /**
+   * Flag to indicate DOM is being updated.
+   * Event handlers should check this to avoid triggering events during updates.
+   */
+  static isUpdating = false
+
+  private debug: boolean
+
+  constructor(debug: boolean = false) {
+    this.debug = debug
+  }
+
+  /**
+   * Generate a stable key for an element.
+   * Used by morphdom to match elements between old and new DOM.
+   */
+  private getNodeKey(node: Node): string | undefined {
+    if (!(node instanceof HTMLElement)) return undefined
+
+    // 1. Use data-on-* handler as key FIRST (stable across renders)
+    for (const attr of node.attributes) {
+      if (attr.name.startsWith('data-on-')) {
+        const key = `${node.tagName}-${attr.name}-${attr.value}`
+        return key
+      }
+    }
+
+    // 2. Use explicit ID (but skip client-generated pywire-uid-* IDs)
+    if (node.id && !node.id.startsWith('pywire-uid-')) {
+      return node.id
+    }
+
+    // 3. Use name attribute for form elements
+    if (
+      node instanceof HTMLInputElement ||
+      node instanceof HTMLSelectElement ||
+      node instanceof HTMLTextAreaElement
+    ) {
+      if (node.name) {
+        return `${node.tagName}-name-${node.name}`
+      }
+    }
+
+    // 4. For other elements, no key (morphdom will use position-based matching)
+    return undefined
+  }
+
+  /**
+   * Generate a selector to find an element
+   */
+  private getElementSelector(el: Element): string {
+    if (el.id) return `#${el.id}`
+
+    // Build a path-based selector
+    const path: string[] = []
+    let current: Element | null = el
+
+    while (current && current !== document.body && path.length < 5) {
+      let selector = current.tagName.toLowerCase()
+
+      // Add distinguishing attributes
+      if (current.id) {
+        selector = `#${current.id}`
+        path.unshift(selector)
+        break // ID is unique enough
+      }
+
+      // Use name for form elements
+      if (
+        current instanceof HTMLInputElement ||
+        current instanceof HTMLSelectElement ||
+        current instanceof HTMLTextAreaElement
+      ) {
+        if (current.name) {
+          selector += `[name="${current.name}"]`
+        }
+      }
+
+      // Use data-on-* for event elements
+      for (const attr of current.attributes) {
+        if (attr.name.startsWith('data-on-')) {
+          selector += `[${attr.name}="${attr.value}"]`
+          break
+        }
+      }
+
+      // Add nth-child for disambiguation
+      if (current.parentElement) {
+        const sibs = Array.from(current.parentElement.children)
+        const sameTags = sibs.filter((s) => s.tagName === current!.tagName)
+        if (sameTags.length > 1) {
+          const idx = sameTags.indexOf(current) + 1
+          selector += `:nth-of-type(${idx})`
+        }
+      }
+
+      path.unshift(selector)
+      current = current.parentElement
+    }
+
+    return path.join(' > ')
+  }
+
+  /**
+   * Capture the current focus state before updating.
+   */
+  private captureFocusState(): FocusState | null {
+    const active = document.activeElement
+    if (!active || active === document.body || active === document.documentElement) return null
+
+    const state: FocusState = {
+      selector: this.getElementSelector(active),
+      id: active.id || null,
+      tagName: active.tagName,
+      selectionStart: null,
+      selectionEnd: null,
+      scrollTop: 0,
+      scrollLeft: 0,
+      value: '',
+    }
+
+    if (active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement) {
+      state.selectionStart = active.selectionStart
+      state.selectionEnd = active.selectionEnd
+      state.scrollTop = active.scrollTop
+      state.scrollLeft = active.scrollLeft
+      state.value = active.value
+    }
+
+    return state
+  }
+
+  /**
+   * Restore focus state after updating.
+   */
+  private restoreFocusState(state: FocusState | null): void {
+    if (!state) return
+
+    // Try to find by ID first, then by selector
+    let el: Element | null = null
+    if (state.id) {
+      el = document.getElementById(state.id)
+    }
+    if (!el && state.selector) {
+      try {
+        el = document.querySelector(state.selector)
+      } catch {
+        // Invalid selector, skip
+      }
+    }
+
+    if (!el) return // Restore focus
+    ;(el as HTMLElement).focus()
+
+    // Restore selection/caret position
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+      // Restore value if it matches what we captured
+      if (state.value && el.value !== state.value) {
+        el.value = state.value
+      }
+
+      if (state.selectionStart !== null && state.selectionEnd !== null) {
+        try {
+          el.setSelectionRange(state.selectionStart, state.selectionEnd)
+        } catch {
+          // Some input types (date, number) don't support setSelectionRange
+        }
+      }
+      el.scrollTop = state.scrollTop
+      el.scrollLeft = state.scrollLeft
+    }
+  }
+
+  private applyUpdate(target: Element, newHtml: string): void {
+    // Set flag to suppress focus/blur events during update
+    DOMUpdater.isUpdating = true
+    if (this.debug) {
+      console.log('[DOMUpdater] Starting update, isUpdating =', DOMUpdater.isUpdating)
+    }
+
+    try {
+      // Capture focus before morphdom runs
+      const focusState = this.captureFocusState()
+
+      if (morphdom) {
+        try {
+          morphdom(target, newHtml, {
+            // Custom key function for stable element matching
+            getNodeKey: (node: Node) => this.getNodeKey(node),
+
+            onBeforeElUpdated: (fromEl, toEl) => {
+              // Transfer ALL relevant state from old element to new element
+
+              // Input/Textarea: preserve value ONLY if they are broadly similar
+              // (e.g. user is still typing or deleted a few chars).
+              // If the server sends a completely different value, let it win.
+              if (fromEl instanceof HTMLInputElement && toEl instanceof HTMLInputElement) {
+                if (fromEl.type === 'checkbox' || fromEl.type === 'radio') {
+                  toEl.checked = fromEl.checked
+                } else {
+                  const s = toEl.value || ''
+                  const c = fromEl.value || ''
+                  if (c.startsWith(s) || s.startsWith(c)) {
+                    toEl.value = c
+                  }
+                }
+              }
+
+              if (fromEl instanceof HTMLTextAreaElement && toEl instanceof HTMLTextAreaElement) {
+                const s = toEl.value || ''
+                const c = fromEl.value || ''
+                if (c.startsWith(s) || s.startsWith(c)) {
+                  toEl.value = c
+                }
+              }
+
+              // Select: preserve selected option
+              if (fromEl instanceof HTMLSelectElement && toEl instanceof HTMLSelectElement) {
+                // Preserve by value (more robust than index)
+                if (
+                  fromEl.value &&
+                  Array.from(toEl.options).some((o) => o.value === fromEl.value)
+                ) {
+                  toEl.value = fromEl.value
+                } else if (
+                  fromEl.selectedIndex >= 0 &&
+                  fromEl.selectedIndex < toEl.options.length
+                ) {
+                  toEl.selectedIndex = fromEl.selectedIndex
+                }
+              }
+
+              // Preserve client-generated IDs (vital for debouncers/throttlers that key off ID)
+              if (fromEl.id && fromEl.id.startsWith('pywire-uid-') && !toEl.id) {
+                toEl.id = fromEl.id
+              }
+
+              return true
+            },
+
+            onBeforeNodeDiscarded: () => true,
+          })
+        } catch (e) {
+          console.error('Morphdom failed:', e)
+          if (target === document.documentElement) {
+            document.open()
+            document.write(newHtml)
+            document.close()
+          }
+        }
+
+        // Restore focus after morphdom completes
+        this.restoreFocusState(focusState)
+      } else if (target === document.documentElement) {
+        document.open()
+        document.write(newHtml)
+        document.close()
+      }
+    } finally {
+      // Clear flag after a microtask to ensure all focus events are suppressed
+      setTimeout(() => {
+        DOMUpdater.isUpdating = false
+      }, 0)
+    }
+  }
+
+  /**
+   * Update the DOM with new HTML content.
+   */
+  update(newHtml: string): void {
+    const hasHtmlRoot = /<html[\s>]/i.test(newHtml)
+    const hasBodyRoot = /<body[\s>]/i.test(newHtml)
+    if (!hasHtmlRoot && document.body) {
+      if (hasBodyRoot) {
+        this.applyUpdate(document.body, newHtml)
+        return
+      }
+      const wrapped = `<body>${newHtml}</body>`
+      this.applyUpdate(document.body, wrapped)
+      return
+    }
+    this.applyUpdate(document.documentElement, newHtml)
+  }
+
+  /**
+   * Update a specific region by its region id.
+   */
+  updateRegion(regionId: string, regionHtml: string): void {
+    const target = document.querySelector(`[data-pw-region="${regionId}"]`)
+    if (!target) {
+      if (this.debug) {
+        console.warn('[DOMUpdater] Region not found:', regionId)
+      }
+      return
+    }
+    this.applyUpdate(target, regionHtml)
+    // Ensure the region anchor remains even if the server HTML omitted it.
+    if (!target.getAttribute('data-pw-region')) {
+      target.setAttribute('data-pw-region', regionId)
+    }
+  }
+}

pywire/client/src/core/index.ts

@@ -0,0 +1,5 @@
+// Core module exports
+export { PyWireApp, PyWireConfig } from './app'
+export { TransportManager, TransportConfig } from './transport-manager'
+export { DOMUpdater } from './dom-updater'
+export * from './transports'