The Fine Print

This framework was built by a human developer and Claude Opus—sometimes seven of them depending on the task. Genius one minute, confidently wrong and clueless the next.

What is a PSPWA?

PSPWA stands for Progressive Single Page Web Application. It's what happens when a PWA and an SPA have a baby, and that baby really cares about user experience.

The pattern of combining PWA capabilities with SPA architecture has been around for years. Gmail does it. Twitter does it. Most modern web apps worth their salt do it. We just gave it a name that's easier to Google.

Traditional Website (1990s)
       ↓
Single Page Application (2010s) — One page, JavaScript handles everything
       ↓
Progressive Web App (2015+) — Installable, offline, push notifications
       ↓
PSPWA (Now) — The obvious combination that everyone was already doing

First visit to /documentation → Fetched from network → Cached by service worker
       ↓
Go offline
       ↓
Visit /documentation again → Served instantly from cache ✓
Visit /some-new-page → Shows friendly offline page (not cached yet)

Philosophy

Funky Frame is built on a set of core principles that guide every architectural decision:

Traditional Request → Server renders HTML → Browser displays
       ↓
    Add JavaScript
       ↓
SPA intercepts links → AJAX loads content → DOM updates smoothly

First Visit:
User clicks /trades → Fetch from server (200ms) → Cache HTML + state

Repeat Visit:
User clicks /trades → Restore from cache (<5ms) → Already done

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                          CLIENT (Browser)                           │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  FunkyJS    │  │   Tables    │  │  Form Modal │  │   Themes    │ │
│  │  Core       │  │  Component  │  │  Component  │  │   System    │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────────────┘ │
│         └────────────────┼────────────────┘                         │
│                          ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                    Funky.Api (HTTP Client)                      ││
│  │              CSRF tokens, error handling, retries               ││
│  └─────────────────────────────────────────────────────────────────┘│
│                          │                                          │
│         ┌────────────────┴───────────────┐                          │
│         ▼                                ▼                          │
│  ┌─────────────────┐              ┌─────────────────┐               │
│  │   REST API      │              │   WebSocket     │               │
│  │   /api/*        │              │   /ws/realtime  │               │
│  └────────┬────────┘              └────────┬────────┘               │
└───────────┼────────────────────────────────┼────────────────────────┘
            │                                │
            ▼                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    YOUR BACKEND (Any Language)                      │
│         Node.js, Python, Ruby, Go, Perl, PHP, .NET, etc.            │
└─────────────────────────────────────────────────────────────────────┘

The Frontend: FunkyJS

The Namespace

All JavaScript lives under the Funky global namespace:

window.Funky = {
    // Core
    Api:        /* HTTP client */,
    Events:     /* DOM event utilities */,
    PubSub:     /* Application pub/sub messaging */,
    Pages:      /* Page lifecycle */,
    SPA:        /* Navigation */,
    Storage:    /* LocalStorage */,
    WebSocket:  /* Real-time connection */,

    // Components
    DataTables: /* Smart table wrapper */,
    FormModal:  /* JSON Schema forms */,
    Toast:      /* Notifications */,
    Wizard:     /* Multi-step forms */,

    // Utilities
    register:   /* Module registration */,
    has:        /* Check if registered */,
};

Secure Registration

Modules are locked after registration—they cannot be overwritten:

Funky.register = function(name, module) {
    if (Funky.has(name)) {
        console.warn('[Funky] Module already registered:', name);
        return false;
    }

    Object.defineProperty(Funky, name, {
        value: Object.freeze(module),
        writable: false,
        configurable: false
    });

    return true;
};

This prevents malicious scripts from hijacking core modules.

Component Pattern

Every component follows the same structure:

(function() {
    'use strict';

    if (Funky.has('MyComponent')) return;

    var MyComponent = {
        // Configuration
        config: { defaultOption: true },

        // Initialization
        init: function(options) {
            this.config = Object.assign({}, this.config, options);
            this.bindEvents();
        },

        // Cleanup
        destroy: function() {
            this.unbindEvents();
        }
    };

    Funky.register('MyComponent', MyComponent);
})();

Security First

CSRF Protection

Every state-changing request requires a CSRF token:

// Funky.Api automatically handles this
Funky.Api.post('/api/trades', tradeData);

// Under the hood:
// 1. Reads token from csrf_token cookie
// 2. Adds X-CSRF-Token header
// 3. Server validates header matches cookie
// 4. Server rotates token after use

Module Protection

Core modules cannot be overwritten after registration:

// First registration succeeds
Funky.register('Api', myApiModule); // → true

// Subsequent attempts fail silently
Funky.register('Api', maliciousModule); // → false
// Console: [Funky] Module already registered: Api

XSS Prevention

Text content is escaped by default in DOM utilities:

// Safe - text is escaped
D.create('div').text(userInput);

// Only use html() with sanitized content
D.create('div').html(sanitizedHtml);

Accessibility

Every component is keyboard navigable, screen reader friendly, and respects motion preferences. We won't claim WCAG perfection—compliance is a moving target. But we've done the work, and we keep improving.

Try it now: Press Tab to navigate, or press F1 to see the keyboard shortcuts panel.

Accessibility is built in, not bolted on. File an issue if something doesn't work with your assistive tech.

Real-Time Everything

WebSocket Connection

A persistent connection delivers updates instantly:

// Automatic connection and reconnection
Funky.WebSocket.connect();

// Subscribe to entity updates
Funky.PubSub.on('ws:entity_change', function(data) {
    if (data.entity === 'trades' && data.action === 'created') {
        Funky.Toast.success('New trade created!');
    }
});

Server → Client Flow

Data Updated (Server)
        ↓
Server broadcasts to WebSocket
        ↓
Client receives: { entity: 'trades', action: 'updated', id: 123 }
        ↓
Page.update() called OR cache invalidated

Smart Updates

Pages declare which entities they care about:

var TradesPage = {
    id: 'trades',
    entities: ['trades', 'trade_allocations'],  // Watch these

    update: function(entity, id, action) {
        // Called when WebSocket announces a change
        this.table.ajax.reload(null, false);
    }
};

Offline Queue

Work offline with confidence. The queue system captures actions when disconnected and syncs automatically when connectivity returns.

How It Works

User actions (creates, updates, deletes) are queued locally when offline. On reconnect, the queue processes automatically with retry logic and conflict resolution.

Conflict Resolution

When offline edits conflict with server changes (HTTP 409), the system supports multiple resolution strategies:

• server-wins — Discard local changes
• client-wins — Force local changes with override header
• merge — Combine server and client data
• prompt — Ask the user to decide

The Page System

Lifecycle

┌──────────────────────────────────────────────────────────────┐
│                        Page Lifecycle                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────┐                                                │
│   │ DORMANT │ ← Page is defined but not active               │
│   └────┬────┘                                                │
│        │ User navigates to page                              │
│        ▼                                                     │
│   ┌──────────┐                                               │
│   │ MOUNTING │ ← init() called, state restored               │
│   └────┬─────┘                                               │
│        ▼                                                     │
│   ┌──────────┐                                               │
│   │  ACTIVE  │ ← Page is visible, WebSocket updates work     │
│   └────┬─────┘                                               │
│        │ User navigates away                                 │
│        ▼                                                     │
│   ┌───────────┐                                              │
│   │ UNMOUNTING│ ← destroy() called, state saved              │
│   └─────┬─────┘                                              │
│         ▼                                                    │
│   ┌──────────┐                                               │
│   │  CACHED  │ ← HTML + state preserved in memory            │
│   └──────────┘                                               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Example Page

var ClientsPage = {
    id: 'clients',
    entities: ['clients', 'client_relationships'],

    init: function(state) {
        // Called when page becomes visible
        this.initDataTable();
        this.bindEvents();

        // Restore scroll position from cached state
        if (state && state.scrollY) {
            window.scrollTo(0, state.scrollY);
        }
    },

    destroy: function() {
        // Called before navigating away
        if (this.table) {
            this.table.destroy();
        }

        // Return state to be cached
        return { scrollY: window.scrollY };
    },

    update: function(entity, id, action) {
        // Called when WebSocket signals change
        if (this.table) {
            this.table.ajax.reload(null, false);
        }
    }
};

Funky.Pages.register(ClientsPage);

Push Notifications

Browser Push with Service Worker

Funky supports native browser push notifications:

// Subscribe the user
Funky.Push.subscribe().then(function(subscription) {
    console.log('Push subscription active');
});

Service Worker Handling

Notifications work even when the app is closed:

// In service worker
self.addEventListener('push', function(event) {
    const data = event.data.json();
    event.waitUntil(
        self.registration.showNotification(data.title, {
            body: data.body,
            icon: data.icon,
            data: data.data
        })
    );
});

// Click handler
self.addEventListener('notificationclick', function(event) {
    event.notification.close();
    event.waitUntil(
        clients.openWindow('/trades/' + event.notification.data.trade_id)
    );
});

Theming System

Three Built-in Themes

CSS Variables

All theming uses CSS custom properties:

:root {
    --pro-bg-primary: #0d1117;
    --pro-bg-secondary: #161b22;
    --pro-text-primary: #e6edf3;
    --pro-accent-primary: #2f81f7;
    /* ... 50+ variables ... */
}

[data-theme="light"] {
    --pro-bg-primary: #ffffff;
    --pro-text-primary: #1f2328;
}

[data-theme="even-funkyer"] {
    --pro-bg-primary: #0a0015;
    --pro-accent-primary: #ff00ff;
    --pro-accent-secondary: #00ffff;
}

User Customization

Funky.Storage.set('user_preferences', {
    theme: 'dark',
    font_scale: 1.1,
    accent_color: '#ff6b35',
    compact_mode: true
});

Testing Framework

Funky includes a built-in JavaScript test runner that executes directly in the browser. No build tools, no Node.js dependency—just pure browser-based testing with real-time feedback.

Writing Tests

Tests are defined using a simple, readable API:

Funky.Test.describe('Button Component', function(it) {
  it('should emit click event', function(assert, done) {
    var btn = D.create('button').text('Click Me');

    E.on(btn.el, 'click', function() {
      assert.ok(true, 'Click event fired');
      done();
    });

    btn.el.click();
  });

  it('should add active class on focus', function(assert) {
    var btn = D.one('.test-button');
    btn.el.focus();
    assert.ok(btn.hasClass('active'), 'Has active class');
  });
});

Why Funky?

Compared to React/Vue/Angular

When to Use Funky