build: add cache to ./configure with -C flag

Add the -C flag to ./configure to enable caching, reducing redundant
resource fetching during builds when packages and the machine remain
unchanged. Caching may cause issues only if applied across different machines
or if packages are modified, neither of which is the case during the build.

.github/workflows/ci-api-docs.yml

@@ -0,0 +1,44 @@
+name: CI API Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'apidocs/**'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'apidocs/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-c-api-docs:
+    runs-on: ubuntu-latest
+    name: Test C API Documentation Generation
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends make doxygen
+      - name: Test C API docs generation
+        run: |
+          cd apidocs/c/
+          doxygen c-prof.conf
+
+  test-python-api-docs:
+    runs-on: ubuntu-latest
+    name: Test Python API Documentation Generation
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends make python3-sphinx
+      - name: Test Python API docs generation
+        run: |
+          cd apidocs/python/
+          sphinx-apidoc -f -o . src && make -j$(nproc) xml SPHINXOPTS="-W --keep-going -n"

.github/workflows/ci-code.yml

@@ -1,10 +1,18 @@
-name: CI
+name: CI Code
 
 on:
   push:
     branches: [master]
+    paths-ignore:
+      - 'docs/**'
+      - 'apidocs/**'
+      - 'README.md'
   pull_request:
     branches: [master]
+    paths-ignore:
+      - 'docs/**'
+      - 'apidocs/**'
+      - 'README.md'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -83,38 +91,10 @@ jobs:
     continue-on-error: true
     steps:
       - uses: actions/checkout@v4
-      - name: install dependencies
+      - name: Install dependencies
         run: |
           sudo apt update
           sudo apt install -y --no-install-recommends codespell
       - name: Check spelling
         run: |
           codespell
-
-  test-c-api-docs:
-    runs-on: ubuntu-latest
-    name: Test C API Documentation Generation
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends make doxygen
-      - name: Test C API docs generation
-        run: |
-          cd apidocs/c/
-          doxygen c-prof.conf
-
-  test-python-api-docs:
-    runs-on: ubuntu-latest
-    name: Test Python API Documentation Generation
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends make python3-sphinx
-      - name: Test Python API docs generation
-        run: |
-          cd apidocs/python/
-          sphinx-apidoc -f -o . src && make -j$(nproc) xml SPHINXOPTS="-W --keep-going -n"

apidocs/c/profhooks.h

@@ -1,220 +1,247 @@
-/** @file
-C Hooks.
-*/
+/** @file profhooks.h
+ * @brief C Plugin Hooks for CProof.
+ *
+ * This header defines optional callback hooks that CProof plugins can implement to
+ * handle events such as startup, shutdown, message processing, and presence updates in
+ * CProof, a console-based XMPP client. These hooks are called by CProof when the
+ * corresponding events occur, allowing plugins to customize behavior. All hooks are
+ * optional; plugins can define only the hooks they need, and CProof will automatically
+ * invoke them when appropriate.
+ *
+ * To use these hooks, define the functions in your plugin with the signatures provided
+ * in this header. For example, to handle the startup event:
+ *
+ * @code
+ * #include "profhooks.h"
+ * void prof_on_start(void) {
+ *     // Handle CProof startup
+ * }
+ * @endcode
+ *
+ * For additional plugin functionality, such as displaying messages or registering
+ * commands, see the CProof API functions in profapi.h.
+ *
+ * @see profapi.h
+ */
+
+/** @mainpage CProof Plugins API and Hooks
+ * List of all API functions available to plugins: @ref profapi.h
+ * List of all hooks which plugins may implement: @ref profhooks.h
+ */
 
 /**
-Called when a plugin is loaded, either when profanity is started, or when the /plugins load or /plugins install commands are called
-@param version the version of Profanity
-@param status the package status of Profanity, "development" or "release"
-@param account_name account name of the currently logged in account, or NULL if not logged in
-@param fulljid the users full Jabber ID (barejid and resource) if logged in, NULL otherwise
-*/
+ * Called when a plugin is loaded, either when CProof is started, or when the /plugins load or /plugins install commands are called
+ * @param version The version of CProof
+ * @param status The package status of CProof, "development" or "release"
+ * @param account_name Account name of the currently logged in account, or NULL if not logged in
+ * @param fulljid The user's full Jabber ID (barejid and resource) if logged in, NULL otherwise
+ */
 void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid);
 
 /**
-Called when Profanity is started
-*/
+ * Called when CProof is started
+ */
 void prof_on_start(void);
 
 /**
-Called when the user quits Profanity
-*/
+ * Called when the user quits CProof
+ */
 void prof_on_shutdown(void);
 
 /**
-Called when a plugin is unloaded with the /plugins unload command
-*/
+ * Called when a plugin is unloaded with the /plugins unload command
+ */
 void prof_on_unload(void);
 
 /**
-Called when the user connects with an account
-@param account_name account name of the account used for logging in
-@param fulljid the full Jabber ID (barejid and resource) of the account
-*/
+ * Called when the user connects with an account
+ * @param account_name Account name of the account used for logging in
+ * @param fulljid The full Jabber ID (barejid and resource) of the account
+ */
 void prof_on_connect(const char * const account_name, const char * const fulljid);
 
 /**
-Called when the user disconnects an account
-@param account_name account name of the account being disconnected
-@param fulljid the full Jabber ID (barejid and resource) of the account
-*/
+ * Called when the user disconnects an account
+ * @param account_name Account name of the account being disconnected
+ * @param fulljid The full Jabber ID (barejid and resource) of the account
+ */
 void prof_on_disconnect(const char * const account_name, const char * const fulljid);
 
 /**
-Called before a chat message is displayed
-@param barejid Jabber ID of the message sender
-@param resource resource of the message sender
-@param message the received message
-@return the new message to display, or NULL to preserve the original message
-*/
+ * Called before a chat message is displayed
+ * @param barejid Jabber ID of the message sender
+ * @param resource Resource of the message sender
+ * @param message The received message
+ * @return The new message to display, or NULL to preserve the original message
+ */
 char* prof_pre_chat_message_display(const char * const barejid, const char *const resource, const char *message);
 
 /**
-Called after a chat message is displayed
-@param barejid Jabber ID of the message sender
-@param resource resource of the message sender
-@param message the received message
-*/
+ * Called after a chat message is displayed
+ * @param barejid Jabber ID of the message sender
+ * @param resource Resource of the message sender
+ * @param message The received message
+ */
 void prof_post_chat_message_display(const char * const barejid, const char *const resource, const char *message);
 
 /**
-Called before a chat message is sent
-@param barejid Jabber ID of the message recipient
-@param message the message to be sent
-@return the modified or original message to send, or NULL to cancel sending of the message
-*/
+ * Called before a chat message is sent
+ * @param barejid Jabber ID of the message recipient
+ * @param message The message to be sent
+ * @return The modified or original message to send, or NULL to cancel sending of the message
+ */
 char* prof_pre_chat_message_send(const char * const barejid, const char *message);
 
 /**
-Called after a chat message has been sent
-@param barejid Jabber ID of the message recipient
-@param message the sent message
-*/
+ * Called after a chat message has been sent
+ * @param barejid Jabber ID of the message recipient
+ * @param message The sent message
+ */
 void prof_post_chat_message_send(const char * const barejid, const char *message);
 
 /**
-Called before a chat room message is displayed
-@param barejid Jabber ID of the room
-@param nick nickname of message sender
-@param message the received message
-@return the new message to display, or NULL to preserve the original message
-*/
+ * Called before a chat room message is displayed
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of message sender
+ * @param message The received message
+ * @return The new message to display, or NULL to preserve the original message
+ */
 char* prof_pre_room_message_display(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called after a chat room message is displayed
-@param barejid Jabber ID of the room
-@param nick nickname of the message sender
-@param message the received message
-*/
+ * Called after a chat room message is displayed
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of the message sender
+ * @param message The received message
+ */
 void prof_post_room_message_display(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called before a chat room message is sent
-@param barejid Jabber ID of the room
-@param message the message to be sent
-@return the modified or original message to send, or NULL to cancel sending of the message
-*/
+ * Called before a chat room message is sent
+ * @param barejid Jabber ID of the room
+ * @param message The message to be sent
+ * @return The modified or original message to send, or NULL to cancel sending of the message
+ */
 char* prof_pre_room_message_send(const char * const barejid, const char *message);
 
 /**
-Called after a chat room message has been sent
-@param barejid Jabber ID of the room
-@param message the sent message
-*/
+ * Called after a chat room message has been sent
+ * @param barejid Jabber ID of the room
+ * @param message The sent message
+ */
 void prof_post_room_message_send(const char * const barejid, const char *message);
 
 /**
-Called when the server sends a chat room history message
-@param barejid Jabber ID of the room
-@param nick nickname of the message sender
-@param message the message to be sent
-@param timestamp time the message was originally sent to the room, in ISO8601 format
-*/
+ * Called when the server sends a chat room history message
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of the message sender
+ * @param message The message to be sent
+ * @param timestamp Time the message was originally sent to the room, in ISO8601 format
+ */
 void prof_on_room_history_message(const char * const barejid, const char *const nick, const char *const message, const char *const timestamp);
 
 /**
-Called before a private chat room message is displayed
-@param barejid Jabber ID of the room
-@param nick nickname of message sender
-@param message the received message
-@return the new message to display, or NULL to preserve the original message
-*/
+ * Called before a private chat room message is displayed
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of message sender
+ * @param message The received message
+ * @return The new message to display, or NULL to preserve the original message
+ */
 char* prof_pre_priv_message_display(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called after a private chat room message is displayed
-@param barejid Jabber ID of the room
-@param nick nickname of the message sender
-@param message the received message
-*/
+ * Called after a private chat room message is displayed
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of the message sender
+ * @param message The received message
+ */
 void prof_post_priv_message_display(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called before a private chat room message is sent
-@param barejid Jabber ID of the room
-@param nick nickname of message recipient
-@param message the message to be sent
-@return the modified or original message to send, or NULL to cancel sending of the message
-*/
+ * Called before a private chat room message is sent
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of message recipient
+ * @param message The message to be sent
+ * @return The modified or original message to send, or NULL to cancel sending of the message
+ */
 char* prof_pre_priv_message_send(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called after a private chat room message has been sent
-@param barejid Jabber ID of the room
-@param nick nickname of the message recipient
-@param message the sent message
-*/
+ * Called after a private chat room message has been sent
+ * @param barejid Jabber ID of the room
+ * @param nick Nickname of the message recipient
+ * @param message The sent message
+ */
 void prof_post_priv_message_send(const char * const barejid, const char * const nick, const char *message);
 
 /**
-Called before an XMPP message stanza is sent
-@param stanza The stanza to send
-@return The new stanza to send, or NULL to preserve the original stanza
-*/
+ * Called before an XMPP message stanza is sent
+ * @param stanza The stanza to send
+ * @return The new stanza to send, or NULL to preserve the original stanza
+ */
 char* prof_on_message_stanza_send(const char *const stanza);
 
 /**
-Called when an XMPP message stanza is received
-@param stanza The stanza received
-@return 1 if Profanity should continue to process the message stanza, 0 otherwise
-*/
+ * Called when an XMPP message stanza is received
+ * @param stanza The stanza received
+ * @return 1 if CProof should continue to process the message stanza, 0 otherwise
+ */
 int prof_on_message_stanza_receive(const char *const stanza);
 
 /**
-Called before an XMPP presence stanza is sent
-@param stanza The stanza to send
-@return The new stanza to send, or NULL to preserve the original stanza
-*/
+ * Called before an XMPP presence stanza is sent
+ * @param stanza The stanza to send
+ * @return The new stanza to send, or NULL to preserve the original stanza
+ */
 char* prof_on_presence_stanza_send(const char *const stanza);
 
 /**
-Called when an XMPP presence stanza is received
-@param stanza The stanza received
-@return 1 if Profanity should continue to process the presence stanza, 0 otherwise
-*/
+ * Called when an XMPP presence stanza is received
+ * @param stanza The stanza received
+ * @return 1 if CProof should continue to process the presence stanza, 0 otherwise
+ */
 int prof_on_presence_stanza_receive(const char *const stanza);
 
 /**
-Called before an XMPP iq stanza is sent
-@param stanza The stanza to send
-@return The new stanza to send, or NULL to preserve the original stanza
-*/
+ * Called before an XMPP iq stanza is sent
+ * @param stanza The stanza to send
+ * @return The new stanza to send, or NULL to preserve the original stanza
+ */
 char* prof_on_iq_stanza_send(const char *const stanza);
 
 /**
-Called when an XMPP iq stanza is received
-@param stanza The stanza received
-@return 1 if Profanity should continue to process the iq stanza, 0 otherwise
-*/
+ * Called when an XMPP iq stanza is received
+ * @param stanza The stanza received
+ * @return 1 if CProof should continue to process the iq stanza, 0 otherwise
+ */
 int prof_on_iq_stanza_receive(const char *const stanza);
 
 /**
-Called when a contact goes offline
-@param barejid Jabber ID of the contact
-@param resource the resource being disconnected
-@param status the status message received with the offline presence, or NULL
-*/
+ * Called when a contact goes offline
+ * @param barejid Jabber ID of the contact
+ * @param resource The resource being disconnected
+ * @param status The status message received with the offline presence, or NULL
+ */
 void prof_on_contact_offline(const char *const barejid, const char *const resource, const char *const status);
 
 /**
-Called when a presence notification is received from a contact
-@param barejid Jabber ID of the contact
-@param resource the resource being disconnected
-@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd"
-@param status the status message received with the presence, or NULL
-@param priority the priority associated with the resource
-*/
+ * Called when a presence notification is received from a contact
+ * @param barejid Jabber ID of the contact
+ * @param resource The resource being disconnected
+ * @param presence Presence of the contact, one of "chat", "online", "away", "xa" or "dnd"
+ * @param status The status message received with the presence, or NULL
+ * @param priority The priority associated with the resource
+ */
 void prof_on_contact_presence(const char *const barejid, const char *const resource, const char *const presence, const char *const status, const int priority);
 
 /**
-Called when a chat window is focused
-@param barejid Jabber ID of the chat window recipient
-*/
+ * Called when a chat window is focused
+ * @param barejid Jabber ID of the chat window recipient
+ */
 void prof_on_chat_win_focus(const char *const barejid);
 
 /**
-Called when a chat room window is focused
-@param barejid Jabber ID of the room
-*/
-void prof_on_room_win_focus(const char *const barejid);
+ * Called when a chat room window is focused
+ * @param barejid Jabber ID of the room
+ */
+void prof_on_room_win_focus(const char *const barejid);

apidocs/python/src/plugin.py

@@ -3,12 +3,14 @@ The plugin module defines optional callback functions that CProof plugins can
 implement to handle events such as startup, shutdown, message processing, and
 presence updates.
 
-::
+All functions are optional and are called by CProof when the corresponding event
+occurs. You need to define them in your module and they will automatically be used
+for callback events.
+
+To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof``
+documentation and use::
 
     import prof
-
-All functions are optional and are called by CProof when the corresponding event
-occurs. String parameters and return values are Python 3 str types.
 """
 
 # Initialization and Lifecycle
@@ -20,18 +22,13 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str
     Called when CProof starts or when the plugin is loaded via the ``/plugins load``
     or ``/plugins install`` commands.
 
-    Args:
-        version: The version of CProof (e.g., ``"1.0.0"``).
-        status: The package status of CProof (``"development"`` or ``"release"``).
-        account_name: The account name of the logged-in user, or None if not logged in.
-        fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
+    :param version: The version of CProof (e.g., ``"1.0.0"``).
+    :param status: The package status of CProof (``"development"`` or ``"release"``).
+    :param account_name: The account name of the logged-in user, or None if not logged in.
+    :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
                 prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}")
@@ -43,15 +40,9 @@ def prof_on_start() -> None:
 
     Use this to perform setup tasks that should occur at application startup.
 
-    Args:
-        None
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_start() -> None:
                 prof.cons_show("CProof has started...")
@@ -63,15 +54,9 @@ def prof_on_shutdown() -> None:
 
     Use this to perform cleanup tasks before the application exits.
 
-    Args:
-        None
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_shutdown() -> None:
                 prof.cons_show("CProof is shutting down...")
@@ -83,15 +68,9 @@ def prof_on_unload() -> None:
 
     Use this to clean up plugin-specific resources.
 
-    Args:
-        None
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_unload() -> None:
                 prof.cons_show("Plugin unloaded")
@@ -101,16 +80,11 @@ def prof_on_unload() -> None:
 def prof_on_connect(account_name: str, fulljid: str) -> None:
     """Called when a user connects to CProof with an account.
 
-    Args:
-        account_name: The account name used for login.
-        fulljid: The full Jabber ID (barejid/resource) of the connected account.
+    :param account_name: The account name used for login.
+    :param fulljid: The full Jabber ID (barejid/resource) of the connected account.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_connect(account_name: str, fulljid: str) -> None:
                 prof.cons_show(f"Connected as {account_name} ({fulljid})")
@@ -120,16 +94,11 @@ def prof_on_connect(account_name: str, fulljid: str) -> None:
 def prof_on_disconnect(account_name: str, fulljid: str) -> None:
     """Called when a user disconnects an account from CProof.
 
-    Args:
-        account_name: The account name being disconnected.
-        fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
+    :param account_name: The account name being disconnected.
+    :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_disconnect(account_name: str, fulljid: str) -> None:
                 prof.cons_show(f"Disconnected {account_name} ({fulljid})")
@@ -144,17 +113,12 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) ->
 
     Allows the plugin to modify or cancel the message display.
 
-    Args:
-        barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
-        resource: The sender's resource (e.g., ``laptop``).
-        message: The received message.
+    :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
+    :param resource: The sender's resource (e.g., ``laptop``).
+    :param message: The received message.
+    :return: The modified message to display, or None to preserve the original.
 
-    Returns:
-        str | None: The modified message to display, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
                 new_message = f"{message} (from {barejid})"
@@ -167,17 +131,12 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) ->
 
     Use this to perform actions after the message is shown.
 
-    Args:
-        barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
-        resource: The sender's resource (e.g., ``laptop``).
-        message: The displayed message.
+    :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
+    :param resource: The sender's resource (e.g., ``laptop``).
+    :param message: The displayed message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
                 prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}")
@@ -189,16 +148,11 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
 
     Allows the plugin to modify or cancel the message.
 
-    Args:
-        barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
-        message: The message to be sent.
+    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
+    :param message: The message to be sent.
+    :return: The modified message to send, or None to cancel sending.
 
-    Returns:
-        str | None: The modified message to send, or None to cancel sending.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
                 return f"{message} (sent by plugin)"
@@ -210,16 +164,11 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None:
 
     Use this to log or react to sent messages.
 
-    Args:
-        barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
-        message: The sent message.
+    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
+    :param message: The sent message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_chat_message_send(barejid: str, message: str) -> None:
                 prof.cons_show(f"Sent to {barejid}: {message}")
@@ -234,17 +183,12 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str
 
     Allows the plugin to modify or cancel the message display.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message sender.
-        message: The received message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message sender.
+    :param message: The received message.
+    :return: The modified message to display, or None to preserve the original.
 
-    Returns:
-        str | None: The modified message to display, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
                 return f"{message} (from {nick})"
@@ -256,17 +200,12 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non
 
     Use this to perform actions after the message is shown.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message sender.
-        message: The displayed message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message sender.
+    :param message: The displayed message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
                 prof.cons_show(f"Displayed in {barejid} from {nick}: {message}")
@@ -278,16 +217,11 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
 
     Allows the plugin to modify or cancel the message.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        message: The message to be sent.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param message: The message to be sent.
+    :return: The modified message to send, or None to cancel sending.
 
-    Returns:
-        str | None: The modified message to send, or None to cancel sending.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
                 return f"{message} (sent by plugin)"
@@ -299,16 +233,11 @@ def prof_post_room_message_send(barejid: str, message: str) -> None:
 
     Use this to log or react to sent messages.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        message: The sent message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param message: The sent message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_room_message_send(barejid: str, message: str) -> None:
                 prof.cons_show(f"Sent to {barejid}: {message}")
@@ -318,18 +247,13 @@ def prof_post_room_message_send(barejid: str, message: str) -> None:
 def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
     """Called when a chat room history message is received from the server.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message sender.
-        message: The received message.
-        timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message sender.
+    :param message: The received message.
+    :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
                 prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}")
@@ -344,17 +268,12 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str
 
     Allows the plugin to modify or cancel the message display.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message sender.
-        message: The received message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message sender.
+    :param message: The received message.
+    :return: The modified message to display, or None to preserve the original.
 
-    Returns:
-        str | None: The modified message to display, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
                 return f"{message} (private from {nick})"
@@ -366,17 +285,12 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non
 
     Use this to perform actions after the message is shown.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message sender.
-        message: The displayed message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message sender.
+    :param message: The displayed message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
                 prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}")
@@ -388,17 +302,12 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N
 
     Allows the plugin to modify or cancel the message.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message recipient.
-        message: The message to be sent.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message recipient.
+    :param message: The message to be sent.
+    :return: The modified message to send, or None to cancel sending.
 
-    Returns:
-        str | None: The modified message to send, or None to cancel sending.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
                 return f"{message} (private to {nick})"
@@ -410,17 +319,12 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
 
     Use this to log or react to sent messages.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-        nick: The nickname of the message recipient.
-        message: The sent message.
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param nick: The nickname of the message recipient.
+    :param message: The sent message.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
                 prof.cons_show(f"Sent private to {nick} in {barejid}: {message}")
@@ -435,15 +339,10 @@ def prof_on_message_stanza_send(stanza: str) -> str | None:
 
     Allows the plugin to modify or cancel the stanza.
 
-    Args:
-        stanza: The XMPP message stanza to send.
+    :param stanza: The XMPP message stanza to send.
+    :return: The modified stanza to send, or None to preserve the original.
 
-    Returns:
-        str | None: The modified stanza to send, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_message_stanza_send(stanza: str) -> str | None:
                 prof.cons_show(f"Sending message stanza: {stanza}")
@@ -456,15 +355,10 @@ def prof_on_message_stanza_receive(stanza: str) -> bool:
 
     Allows the plugin to control whether CProof processes the stanza.
 
-    Args:
-        stanza: The received XMPP message stanza.
+    :param stanza: The received XMPP message stanza.
+    :return: True to allow CProof to process the stanza, False to block processing.
 
-    Returns:
-        bool: True to allow CProof to process the stanza, False to block processing.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_message_stanza_receive(stanza: str) -> bool:
                 prof.cons_show(f"Received message stanza: {stanza}")
@@ -477,15 +371,10 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None:
 
     Allows the plugin to modify or cancel the stanza.
 
-    Args:
-        stanza: The XMPP presence stanza to send.
+    :param stanza: The XMPP presence stanza to send.
+    :return: The modified stanza to send, or None to preserve the original.
 
-    Returns:
-        str | None: The modified stanza to send, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_presence_stanza_send(stanza: str) -> str | None:
                 prof.cons_show(f"Sending presence stanza: {stanza}")
@@ -498,15 +387,10 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool:
 
     Allows the plugin to control whether CProof processes the stanza.
 
-    Args:
-        stanza: The received XMPP presence stanza.
+    :param stanza: The received XMPP presence stanza.
+    :return: True to allow CProof to process the stanza, False to block processing.
 
-    Returns:
-        bool: True to allow CProof to process the stanza, False to block processing.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_presence_stanza_receive(stanza: str) -> bool:
                 prof.cons_show(f"Received presence stanza: {stanza}")
@@ -519,15 +403,10 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None:
 
     Allows the plugin to modify or cancel the stanza.
 
-    Args:
-        stanza: The XMPP IQ stanza to send.
+    :param stanza: The XMPP IQ stanza to send.
+    :return: The modified stanza to send, or None to preserve the original.
 
-    Returns:
-        str | None: The modified stanza to send, or None to preserve the original.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_iq_stanza_send(stanza: str) -> str | None:
                 prof.cons_show(f"Sending IQ stanza: {stanza}")
@@ -540,15 +419,10 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool:
 
     Allows the plugin to control whether CProof processes the stanza.
 
-    Args:
-        stanza: The received XMPP IQ stanza.
+    :param stanza: The received XMPP IQ stanza.
+    :return: True to allow CProof to process the stanza, False to block processing.
 
-    Returns:
-        bool: True to allow CProof to process the stanza, False to block processing.
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_iq_stanza_receive(stanza: str) -> bool:
                 prof.cons_show(f"Received IQ stanza: {stanza}")
@@ -562,17 +436,12 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool:
 def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
     """Called when a contact goes offline.
 
-    Args:
-        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
-        resource: The resource being disconnected (e.g., ``laptop``).
-        status: The status message received with the offline presence, or None.
+    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
+    :param resource: The resource being disconnected (e.g., ``laptop``).
+    :param status: The status message received with the offline presence, or None.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
                 prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}")
@@ -582,19 +451,14 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) ->
 def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
     """Called when a presence notification is received from a contact.
 
-    Args:
-        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
-        resource: The resource of the contact (e.g., ``laptop``).
-        presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``).
-        status: The status message received with the presence, or None.
-        priority: The priority associated with the resource.
+    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
+    :param resource: The resource of the contact (e.g., ``laptop``).
+    :param presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``).
+    :param status: The status message received with the presence, or None.
+    :param priority: The priority associated with the resource.
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
                 prof.notify(f"{barejid} is {presence}", 5000, "Presence")
@@ -607,15 +471,10 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status:
 def prof_on_chat_win_focus(barejid: str) -> None:
     """Called when a chat window is focused.
 
-    Args:
-        barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
+    :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_chat_win_focus(barejid: str) -> None:
                 prof.cons_show(f"Focused chat window for {barejid}")
@@ -625,17 +484,12 @@ def prof_on_chat_win_focus(barejid: str) -> None:
 def prof_on_room_win_focus(barejid: str) -> None:
     """Called when a chat room window is focused.
 
-    Args:
-        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+    :return: None
 
-    Returns:
-        None
-
-    Example:
-
-        ::
+    Example::
 
             def prof_on_room_win_focus(barejid: str) -> None:
                 prof.cons_show(f"Focused room window for {barejid}")
     """
-    pass
+    pass

src/ui/buffer.c

@@ -1,40 +1,36 @@
 /*
  * buffer.c
- * vim: expandtab:ts=4:sts=4:sw=4
+ *
+ * Message buffer implementation for CProof.
+ *
+ * This module provides an in-memory buffer for managing active chat entries in the
+ * console-based XMPP client. Separate from persistent SQLite storage, it holds
+ * messages and metadata solely for UI rendering, ensuring responsive scrolling and
+ * display without exceeding ncurses pad limits (10k lines). By tracking rendered
+ * line counts per entry, it proactively trims content to prevent overflow, enabling
+ * seamless integration with ncurses for position-aware rendering.
+ *
+ * Key features and operations:
+ *   - Append/prepend entries (messages) with automatic line-based cleanup.
+ *   - Track cumulative lines for overflow prevention and efficient buffer sizing.
+ *   - Remove entries by ID or index; mark delivery receipts as received.
+ *   - Retrieve entries by index or ID for rendering and history queries.
+ *   - Store metadata including timestamps, senders, themes, and ncurses y-positions.
+ *
+ * CProof. Fork of Profanity (since 2025).
  *
  * Copyright (C) 2012 - 2019 James Booth <boothj5@gmail.com>
  * Copyright (C) 2019 - 2025 Michael Vetter <jubalh@iodoru.org>
+ * Copyright (C) 2025 CProof Developers
  *
- * This file is part of Profanity.
- *
- * Profanity is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * Profanity is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with Profanity.  If not, see <https://www.gnu.org/licenses/>.
- *
- * In addition, as a special exception, the copyright holders give permission to
- * link the code of portions of this program with the OpenSSL library under
- * certain conditions as described in each individual source file, and
- * distribute linked combinations including the two.
- *
- * You must obey the GNU General Public License in all respects for all of the
- * code used other than OpenSSL. If you modify file(s) with this exception, you
- * may extend this exception to your version of the file(s), but you are not
- * obligated to do so. If you do not wish to do so, delete this exception
- * statement from your version. If you delete this exception statement from all
- * source files in the program, then also delete it here.
+ * Licensed under the GNU General Public License, version 3,
+ * with the OpenSSL exception. See LICENSE for details.
  *
+ * vim: expandtab:ts=4:sts=4:sw=4
  */
 
 #include "config.h"
+#include "ui/window_list.h"
 
 #include <stdlib.h>
 #include <string.h>
@@ -54,15 +50,8 @@
 #include "ui/window.h"
 #include "ui/buffer.h"
 
-#define MAX_BUFFER_SIZE     200
 #define STRDUP_OR_NULL(str) ((str) ? strdup(str) : NULL)
 
-struct prof_buff_t
-{
-    GSList* entries;
-    int lines;
-};
-
 static void _free_entry(ProfBuffEntry* entry);
 static ProfBuffEntry* _create_entry(const char* show_char, int pad_indent, GDateTime* time, int flags, theme_item_t theme_item, const char* const display_from, const char* const from_jid, const char* const message, DeliveryReceipt* receipt, const char* const id, int y_start_pos, int y_end_pos);
 static void _buffer_add(ProfBuff buffer, const char* show_char, int pad_indent, GDateTime* time, int flags, theme_item_t theme_item, const char* const display_from, const char* const from_jid, const char* const message, DeliveryReceipt* receipt, const char* const id, int y_start_pos, int y_end_pos, gboolean append);
@@ -108,23 +97,24 @@ _buffer_add(ProfBuff buffer, const char* show_char, int pad_indent, GDateTime* t
 
     buffer->lines += e->_lines;
 
-    while (g_slist_length(buffer->entries) >= MAX_BUFFER_SIZE) {
+    // With 10% margin to ensure overflow prevention
+    while (buffer->lines >= PAD_SIZE - (PAD_SIZE / 10) && g_slist_length(buffer->entries) > 1) {
         // Delete message from the opposite size to free buffer
         GSList* buffer_entry_to_delete = append ? buffer->entries : g_slist_last(buffer->entries);
         ProfBuffEntry* entry_to_delete = (ProfBuffEntry*)buffer_entry_to_delete->data;
+        // log_debug("(Messages left in buffer: %d) DELETING: %s", g_slist_length(buffer->entries), entry_to_delete->id);
         buffer->lines -= entry_to_delete->_lines;
         _free_entry(entry_to_delete);
         buffer->entries = g_slist_delete_link(buffer->entries, buffer_entry_to_delete);
     }
 
     if (from_jid && y_end_pos == y_start_pos) {
-        log_warning("Ncurses Overflow! From: %s, position: %d, ID: %s, append: %s, used message buffer size: %d, message buffer size: %d, rendered lines buffer size: %d",
-                    from_jid, y_start_pos, id, append ? "TRUE" : "FALSE", g_slist_length(buffer->entries), MAX_BUFFER_SIZE, PAD_SIZE);
-        // At this point we have a message that caused overflow of the render buffer.
-        // Ideally, we want to clean other messages to rerender everything properly. To do so,
-        // first we need to determine the size of the message that we are trying to display,
-        // then we need to print the message.
-        // However, _buffer_add is too late in the code to do this, therefore it has to be done in the win_print_old_history.
+        // win_redraw will redraw with entries above removed,
+        // it will also recalculate actual size of the message that caused overflow
+        int old_lines = buffer->lines;
+        win_redraw(wins_get_current());
+        log_debug("Ncurses Overflow! From: %s, position: %d, ID: %s, append: %s, used message buffer size: %d, rendered lines: (old: %d/ actual: %d/ max: %d)",
+                  from_jid, y_start_pos, id, append ? "TRUE" : "FALSE", g_slist_length(buffer->entries), old_lines, buffer->lines, PAD_SIZE);
     }
 
     buffer->entries = append ? g_slist_append(buffer->entries, e) : g_slist_prepend(buffer->entries, e);

src/ui/buffer.h

@@ -68,6 +68,12 @@ typedef struct prof_buff_entry_t
     char* id;
 } ProfBuffEntry;
 
+struct prof_buff_t
+{
+    GSList* entries;
+    int lines;
+};
+
 typedef struct prof_buff_t* ProfBuff;
 
 ProfBuff buffer_create();

src/ui/window.c

@@ -2003,6 +2003,10 @@ win_redraw(ProfWin* window)
             _win_print_internal(window, e->show_char, e->pad_indent, e->time, e->flags, e->theme_item, e->display_from, e->message, e->receipt);
         }
         e->y_end_pos = getcury(window->layout->win);
+        // Recalculate lines (might be incorrect in case of NCurses overflow)
+        window->layout->buffer->lines -= e->_lines;
+        e->_lines = e->y_end_pos - e->y_start_pos;
+        window->layout->buffer->lines += e->_lines;
     }
 }