Back to WebPal 4

WebPal Release Notes — Version 4.0

Branch: webpal4
Coverage: All PRs merged up to 2026-04-23 (100 PRs, #1133–#1390)
Document type: Internal technical reference

How to Read This Document

  • vs. WebPal 3: Sections describing what changed relative to the master branch describe the WebPal 3 experience first, then the v4 improvement.
  • PR references: Written as #NNNN and link to GitHub pull requests.
  • Issue references: Written as issue #NNNN.
  • Code references: Written as path/to/file.php:line where applicable.

Release 4.0.1 — Summary

WebPal 4 is a major-version release that rebuilds the frontend from a custom jQuery SPA into a component-based SPA using Inertia.js and Vue 3, while retaining the mature document management and CMS backend. The visual design adopts a GitHub-inspired interface language — prioritising clarity, speed, and functional density — and translates developer-oriented patterns from that model into vocabulary and workflows suited to general business users.

The headline addition is the AI Flow platform: a fully integrated agentic AI system (Vizra ADK) that gives users and administrators programmable AI agents capable of operating directly on documents, users, and external systems. A large number of WebPal 3 subsystems have also been rebuilt, modernised, or significantly extended.

Contents

Part 1: Improvements to Existing Features

Part 2: New Features

Part 3: Developer & Operations

Part 1: Improvements to Existing WebPal 3 Features

1.1 User Interface Architecture

WebPal 3 (master)

WebPal 3 uses a custom jQuery single-page application delivered by a single Blade template with a large suite of jQuery plugins (jstree, jqGrid, jQuery UI layout, jQuery File Upload, CKEditor 4). Backend communication uses a command-dispatch AJAX API rather than RESTful endpoints. Real-time broadcasting existed but was largely unused in standard installations.

WebPal 4

The entire primary application has been rebuilt with Inertia.js + Vue 3 + TypeScript. The command-dispatch API is replaced with conventional REST endpoints. Build tool is Vite. State managed with Pinia stores. Three-panel layout consistent across Documents, Sites, and Flow sections.

Design language — GitHub-inspired: The WebPal 4 interface is explicitly modelled on GitHub's UI: high information density, functional clarity, fast perceived performance, minimal visual footprint. Developer-optimized patterns are adapted for general business end-users.

New UI Features

  • Full dark mode coverage across all sections
  • User avatars throughout the UI
  • Toast notifications (transient and sticky)
  • Responsive layout (mobile, tablet, desktop breakpoints)
  • Cursor-style pagination and load-more patterns
  • Zoom controls for HTML preview and PDF viewer
  • Breadcrumb tooltips with full path on hover

Relevant PRs: #1141, #1143, #1145, #1146, #1165, #1188, #1210, #1225, #1227, #1299, #1381

1.2 Document Management UI

  • Tile View — OneDrive-style multi-select: click to select, Ctrl+Click to toggle, Shift+Click for range (#1160, #1210)
  • Breadcrumb tooltips — Full folder name on hover (#1148, issue #1123)
  • Post-delete redirect — Redirects to valid parent instead of broken state (#1221, issue #1179)
  • Accurate refresh on upload — Real-time broadcast synchronisation for shared documents (#1221)
  • Folder picker modal — Pre-opens known nodes, aligned action buttons (#1224, issues #1176, #1177)
  • New folder reliability — Fixed state sync, submission on blur, closed root node behaviour (#1248, issues #1164, #1170, #1172)
  • Folder rename via breadcrumb — Now works when viewing folder with nothing selected (#1321, issue #1180)
  • Actions menu consolidation — Single component backed by composables (#1145, #1188, issue #1182)
  • Left panel search — "Go to file" search no longer closes on panel resize (#1239, issue #1173)

1.4 Document Editing

HTML Files (*.html, *.htm, *.wdoc)

  • Monaco Editor — VS Code engine replaces CKEditor (#1238, issue #1200)
  • Split-pane layout — Editor (left) + live preview (right) with three view modes (#1238)
  • Server-side Chromium rendering — Preview via Puppeteer at 1920×1080 WebP, JavaScript executes correctly (#1238)
  • WebSocket delivery — Preview regenerates after auto-save via broadcast (#1238, doc/html-preview.md)
  • Auto-refresh — Monaco auto-saves and refreshes when file edited externally (#1366, issue #1363)
  • Configurable queue — HTML_PREVIEW_QUEUE env var (#1326)

Markdown Files

  • Discard Changes button added (#1348, issue #1302)
  • Preview flashing eliminated when switching modes (#1348)
  • GFM (GitHub Flavored Markdown) rendering improved (#1348)
  • Ctrl+Z undo no longer broken by chat textarea focus (#1328, issue #1244)

All Editors

  • Dark mode support for WYSIWYG editor (#1240)
  • Collapsible code blocks in chat markdown (#1228)

1.5 File Upload

  • Drag-and-drop upload — Drag OS files onto Documents list. 10 unit tests. (#1368, issue #1365)
  • Paste-to-upload — Ctrl+V in Documents list, CKEditor, Monaco. Images embedded inline. (#1380, issues #1364, #1226)
  • Chat attachments — Files pasted in AI chat stored in /Home/attached-documents (#1388, issue #1387)

1.6 File Conversion

  • Markdown to Word (DOCX) conversion (#1140)
  • Expanded PDF conversion for additional file types (#1140)
  • Agent-accessible conversion tools: document_convert and document_convert_info (#1271)

1.7 File Previews

  • Polished "preview not available" UI with centered placeholder (#1317, issue #1193)
  • Separate "preview generating" state messaging (#1325, issue #1211)
  • Thumbnail generation backoff retry logic. 25 tests. (#1276, issue #1277)

1.8 Document Versioning

Re-uploading a file with the same name now records the prior version and displays it in a dedicated Version History panel. Users can browse and restore previous versions. (#1315, issues #1003, #1004, #1006)

1.9 Document Activity History

  • History tab in document detail panel shows uploads, edits, shares, emails (#1245)
  • Permission improvements — respects user's actual document permissions
  • "Attach documents to email" activity now surfaced (#1385, issue #1316)

1.10 Sharing & Permissions

Permission checkboxes in Share Dialog are now disabled when the sharing user doesn't hold that permission. Read-only users cannot grant Upload, Delete, or Share rights. (#1336, issue #1011, #1275)

1.11 User Management

  • Users page rewrite — Inertia/Vue 3 with create/delete APIs. 12 tests. (#1390, issue #1374)
  • Group management UI — Create, edit, delete groups and manage memberships. 19 tests. (#1350, issue #1332)
  • Recipient lookup hardening — RecipientService with guest/non-admin scoping. 30 tests. (#1335, issue #1333)

1.12 Authentication

  • Login accepts username or email (field type changed to "text") (#1311, issue #1288)
  • Configurable Remember Me checkbox (#1311)
  • Forgot Password flow fixed (#1311)
  • Create Account link visibility configurable (#1311)
  • Profile update 500 error fixed — NULL lang column hardened (#1352, issue #1351)

1.13 Email System

  • Laravel Mail replaces PHPMailer dependency (#1296, issue #953)
  • Blade email templates matching WebPal 4 design (#1337, issue #1039)
  • Attach-documents-to-email bug fixed (#1296)

1.14 WebDAV

Fixed regression: Request instance binding now happens before kernel bootstrap to prevent TypeError. (#1149)

1.15 Performance

  • Frontend: Vue 3 + Inertia.js eliminates full-page reloads, sends only data diffs
  • Database: Covering index on file_history eliminates 150 filesorts per page load (#1249)
  • Build: Pre-built distributions symlinked, dramatically reducing Vite build times (#1214, issue #1213)
  • Runtime: Docs tab in AI chat optimized to avoid re-renders (#1161)
  • Thumbnail: Backoff retry prevents indefinite queue blocking (#1276)

1.16 Shell Script Portability

All 126 shell scripts updated from hardcoded #!/bin/bash to #!/usr/bin/env bash for portability across Linux distributions. All verified with bash -n. (#1274)

1.17 Real-Time Asynchronous UI Updates

Real-time broadcasting is now integral to the UI via Laravel Reverb (WebSocket) and Laravel Echo. Actions by any user or AI agent trigger immediate updates to all connected clients.

Event Channel Purpose
FileChangedprivate-documents.{id}File/folder created, renamed, moved, deleted
FolderContentChanged(triggers FileChanged)Folder contents changed
ShareContentChangedprivate-shares.{shareId}Shared document/folder modified
DocumentEditChunkprivate-documents.{id}.editsStreaming AI edit chunk
DocumentEditCompleteprivate-documents.{id}.editsStreaming AI edit completed
HtmlPreviewReadyprivate-files.{id}Server-side HTML preview generated
NewChatChunkprivate-App.Models.User.{userId}Streaming LLM response token
StreamCompleteprivate-App.Models.User.{userId}LLM streaming finished
AgentProcessStatusprivate-flow-statusAgent processing step status
AgentDefinitionChangedprivate-flow-statusAgent created/deleted
UserNotificationprivate-App.Models.User.{userId}Push toast notification
FrontEndActionprivate-App.Models.User.{userId}Backend triggers frontend action

Part 2: New Features

2.1 AI Flow Platform

The most significant new capability in WebPal 4. The Flow section is a built-in agentic AI platform powered by Vizra ADK, integrated directly into WebPal's document management environment. Agents can converse with users, act on documents, call external systems, trigger each other, and run autonomously in the background.

Key Components

  • Flow Page (/flow): Dashboard tab with KPI cards and status charts; History tab with paginated conversations (#1222, #1307, #1353)
  • Agent Types: LLM Agents (conversational), Workflow Agents (multi-step pipelines), Event-Triggered Agents (background automation)
  • Agent Detail Panel: Diagram tab (live Mermaid.js visualization), Activity tab, Prompt tab (in-browser Monaco editor), Description panel
  • No-Code Agent Development: AgentCreator builds custom agents through conversation — no PHP coding required (#1255, issue #1253)
  • Event Triggers: FileChanged, FolderContentChanged, IncomingEmailReceived with configurable filters (#1230, issue #1229)
  • Workflow Orchestration: Sequential and parallel execution with configurable failure modes, logged to workflow_execution_logs
  • Real-Time Streaming Edits: EditorAgent streams document changes character-by-character via WebSocket
  • Agent Status Management: Flow Dashboard, session cards with terminate button, admin session management
  • LLM Streaming & Token Tracking: StreamingAgentRunner, token counts stored on agent_messages (#1314, #1324, #1347)
  • Agent Chat Interface: Prompt history (Ctrl+Up/Down), context reset markers, status messages, multimodal input (#1161, #1339, #1388)
  • Context Awareness: Agent tracks user's current document/folder context (#1219)
  • Sub-Agents: Delegation support via DelegateToSubAgentTool (#1234, issue #1232)
  • Toast Notifications: Agents push real-time toasts via SendNotificationTool (#1233, issue #1231)
  • Export/Import: php artisan agent:export/import for portable agent archives (#1236, issue #1235)
  • Per-User API Credentials: Settings → Credentials page for tool authentication (#1281, issue #1260)
  • LLM-as-Judge Framework: Testing framework with exact-match, contains, and LLM evaluation assertions (#1195, issue #1194)

2.2 Built-in AI Agents

Interactive Agents

AgentDescription
doc_agentBrowse, read, edit, search, convert documents with sandboxed scratch directory
editor_agentReal-time streaming document edits to open CKEditor
user_adminCreate, edit, manage user accounts and groups
webpal_adminSystem administration with user_admin as sub-agent
chat_adminQuery and export conversation history with token usage
agent_creatorCreate, modify, delete custom agents through conversation
pipedrive_agentQuery and update PipeDrive CRM
zabbix_agentQuery Zabbix monitoring for metrics and alerts

Background/Workflow Agents

AgentDescription
meeting_summary_workflowEmail-triggered: summarize meeting, save Markdown, notify via Slack/email
summarize_emailStep 1 of meeting workflow: structured Markdown summary
email_processorGeneral-purpose background email processing
notification_emailSend email notification as workflow step
notification_slackSend Slack notification as workflow step

2.3 AI Image Generation

ImageGenerationAgent wraps Vizra ADK's ImageAgent with smart drive resolution and integration with AgentCreator. (#1293, issue #1292)

2.4 External Integration: PipeDrive CRM

Five agent tools for PipeDrive API: query deals/leads/persons, add deal notes, update deals. (#1223, issue #1128)

2.5 External Integration: GitHub

Ten tools for GitHub: query issues/PRs/repos, create/update issues, add comments, manage labels, GraphQL queries, raw GET requests. (#1136, #1257)

2.6 External Integration: Time Tracker

SubmitActivityTool and TimeTrackerTool for logging time entries against GitHub issues. (#1259, issue #1258)

2.7 External Integration: Zabbix Monitoring

QueryZabbixTool for host metrics, network traffic, storage, active alerts. Historical data up to 30 days. Multiple server support.

2.8 External Integration: Slack

SendSlackMessageTool for posting to channels with threading, mrkdwn formatting, link unfurling control.

2.9 External Integration: PDF Manipulation

Four PDF tools backed by PdfService: merge, split, encrypt, compress. Input/output by WebPal document IDs.

2.10 Agent Filesystem Tools

Sandboxed scratch directories per chat session for multi-step file operations. ChatCreated broadcast event. (#1154)

2.11 DrawIO Diagram Editor

"New > DrawIO Diagram" action in DocumentActionsMenu. Embedded Draw.io editor in Vue. (#1243, issue #1134)

2.12 Home Dashboard

New Home Dashboard with unified recent activity feed, filter controls, AI token usage display. Context tiles link to documents. (#1307, #1353, #1383)

2.13 Laravel Dusk End-to-End Testing

DuskTestCase base class with login() helper, 2FA handling, debug screenshots. (#1251)

2.14 PHPUnit Test Suite

All tests annotated with #[Group('minimal')]. Running php artisan test --group=minimal executes 1,908 environment-independent tests. (#1322, #1362, issue #1354)

Part 3: Developer and Operational Improvements

Key Developer Improvements

  • Agent Tool Parameter Pattern: Use !empty() instead of ?? null to handle LLM empty strings (#1186, #1257)
  • Triggered Agent Ownership: Explicit user ownership, fails loudly if run-as user deleted (#1230, issue #1229)
  • Test Infrastructure: Fixed invalid MySQL table names, removed hardcoded credentials, stabilized suite (#1138, #1190, #1264, #1341, #1344, #1362)
  • Temporary File Leaks: Fixed cleanup on exception paths (#1190, issue #1189)
  • Duplicate Declarations: Fixed Cannot redeclare errors (#1264, #1188)

Appendix: Full PR Index for 4.0.1

All 100 PRs merged into webpal4 branch (#1133–#1390)

For the complete PR index with all 100 pull requests, please refer to the source document: tmp/release-notes-v-401.md
Return to WebPal 4 Overview