ICECHAT NX v1.6.5
Next-Generation SysOp Paging & ATDT Private-Line Chat
=====================================================

IceChat NX is an ATDT Native PHP paging door plus a native Windows x64 SysOp
client. Callers can page the SysOp; the Windows client alerts immediately with
the classic IceChat-derived page tune. When the SysOp accepts, IceChat NX now
bridges the conversation into ATDT's built-in private SysopChat screen.

NO ATDT CORE FILES ARE MODIFIED OR REPLACED.

REQUIREMENT
-----------

IceChat NX v1.6.5 requires an ATDT build with the native private SysOp chat
components used by the bridge: Atdt\Chat, SysopChatScreen, the chat_msgs queue,
and normal caller background polling. The bridge uses those existing ATDT
features and does not patch api.php, term.js, lib/, or any other ATDT file.

PACKAGE LAYOUT
--------------

  doors/icechatnx/
      .htaccess
      api.php
      config.php
      door.json
      door.php
      lib/PageStore.php
      display/main.ans
      display/README.TXT

  windows-client/
      IceChatNX.exe
      CONFIG/config.json
      DOCS/PAGE-ICE-CONVERSION.TXT
      ASSETS/PAGE.wav
      ASSETS/IceChatNX.ico

  source/windows-native/
      main.go
      PAGE.wav
      BUILD.TXT


CUSTOM OPENING ANSI
-------------------

The first screen shown when a caller enters IceChat NX is loaded from:

  /doors/icechatnx/display/main.ans

The supplied file recreates the default IceChat NX opening screen, but it is a
normal CP437 ANSI file and may be replaced by the SysOp. An 80x25 design is
recommended for the ATDT terminal. ATDT's CP437 loader is used, so standard
ANSI escape sequences and SAUCE records are supported.

The following ASCII placeholder tokens are replaced at runtime:

  @VERSION@
  @CALLER@
  @SYSOP@
  @SYSOP_STATUS@
  @SYSOP_COLOR@
  @CLIENT_NAME@
  @HEARTBEAT@
  @STATUS_MESSAGE@
  @STATUS_LINE@
  @MESSAGE_COLOR@

See doors/icechatnx/display/README.TXT for details and examples. If main.ans
is unavailable or unusable, IceChat NX automatically draws its original
built-in main screen instead.

ATDT STORAGE MODEL
------------------

Door code is installed in:

  /doors/icechatnx/

Writable/runtime IceChat NX data is stored in ATDT's private per-door store:

  /data/doorstore/icechatnx/

Expected runtime files:

  /data/doorstore/icechatnx/pages.json
  /data/doorstore/icechatnx/client.json
  /data/doorstore/icechatnx/chatlogs/*.log

The actual live private conversation is transported through ATDT's existing
chat_msgs database queue. IceChat NX mirrors those private-line rows into its
own pages.json rolling transcript and permanent chatlogs/ files.

INSTALL - ATDT SERVER
---------------------

1. Confirm the board's ATDT build includes the native private SysOp chat
   components used by IceChat NX.

2. Upload the complete folder to:

     /doors/icechatnx/

3. In the ATDT SysOp console, open Doors and Scan/register IceChat NX.

4. Open IceChat NX's admin panel. On a new install, click Generate new key.
   No shared API key is shipped with IceChat NX. The Admin Panel then shows the
   full API URL and generated API key used by the Windows client.

5. Add a DOOR menu action with argument:

     icechatnx

6. Open the door once. IceChat NX creates its writable storage under:

     /data/doorstore/icechatnx/

No ATDT root/core PHP or JavaScript file is replaced or patched.

WINDOWS CLIENT
--------------

1. Copy windows-client/ to the SysOp Windows computer.

2. Before linking the Windows client, open the IceChat NX Admin Panel in ATDT
   and click Generate new key. Then start IceChatNX.exe. On first launch the
   native Link to BBS window opens automatically. Copy both values from the
   IceChat NX Admin Panel:

     API URL: https://www.yourdomain.com/doors/icechatnx/api.php
     API KEY: <the newly generated key shown in the Admin Panel>

   Click Save. The EXE protects the API key with Windows DPAPI and writes only
   the encrypted key blob to CONFIG/config.json; manual JSON editing is not
   required. An existing plaintext api_token from an older client is migrated
   automatically the next time v1.6.5 loads that configuration.

3. The API URL or API KEY can later be changed using Link to BBS in the main GUI,
   Options menu, or tray menu.

4. Optional: enable or disable Auto Start with Windows from the client's
   Options menu. No helper scripts are required.

The Windows client is a native x64 GUI executable. It does not launch
PowerShell and has no execution-policy dependency.

HOW LIVE CHAT WORKS IN v1.6.5
-----------------------------

1. Caller enters IceChat NX and sends a page.
2. IceChat NX records the caller's ATDT node and exact live session identity.
3. The Windows client receives the page.
4. SysOp clicks Accept Chat.
5. /doors/icechatnx/api.php validates that the same caller/session is still
   online, then uses ATDT's existing Atdt\Chat::post() private-line queue.
6. ATDT's normal caller background poll sees the private SysOp line and pushes
   its built-in SysopChat screen over the current caller screen.
7. ATDT handles async SysOp -> caller delivery while preserving a half-typed
   caller line. The caller no longer needs F5/Refresh Chat and IceChat NX does
   not query its own chat store on each caller keystroke.
8. Caller replies are written by ATDT to chat_msgs. The IceChat NX API mirrors
   them to the Windows client and permanent IceChat NX transcript.
9. When the caller leaves the ATDT private line, IceChat NX detects that the
   SysopChat screen is no longer active and marks the page chat ended.

ATDT's existing caller background poll handles SysOp -> caller delivery, so
the private line remains near real-time without any IceChat NX core patch.

CALLER EXPERIENCE
-----------------

Before acceptance, the caller remains in the IceChat NX paging/status door.
After acceptance, ATDT automatically opens its normal private SysOp chat line.
The caller uses ATDT's standard private-line input behavior rather than an
IceChat NX-specific F5 refresh screen.

Ending from the Windows client sends ATDT's normal sysophup marker. The caller
sees ATDT's standard private-line-ended notice and exits the line using ATDT's
normal blank-line/ESC behavior.

SESSION SAFETY
--------------

IceChat NX stores the caller node, ATDT session id, session-created timestamp,
and user id with each new page. Accept Chat revalidates that same live session
before posting the private message. This prevents an old page aimed at a
recycled node number from opening a conversation with a different caller.

WINDOWS CHAT GUI
----------------

The native Windows chat window remains automatic:

  * It polls IceChat NX for new mirrored ATDT private-line messages.
  * Send writes a private ATDT SysOp message to the caller's node.
  * Refresh remains available as a manual Windows-side fallback.
  * End Chat sends ATDT's built-in private-line hang-up marker.

The IceChat NX API also keeps ATDT's console heartbeat fresh while a bridged
chat is active, preventing the built-in private screen from incorrectly saying
the SysOp has stepped away while the Windows client is actively connected.

CHAT LOGS
---------

Accepted chats are permanently transcribed under:

  /data/doorstore/icechatnx/chatlogs/

Example:

  2026-09-22_page-000017_xendrome.log

ATDT private-line message ids are deduplicated before they are appended, so
repeated Windows polls do not duplicate transcript lines.

The rolling queue/message retention in pages.json does not rotate the separate
chatlog files. Back up chatlogs if you need to preserve them before using
ATDT's Remove + data function.

PAGE TUNE
---------

IceChatNX.exe embeds PAGE.wav converted from the supplied legacy PAGE.ICE tune.
It is the default alert sound:

  "page_tune": "embedded"

An external WAV may be configured by putting a filename or full path in
page_tune. When the SysOp successfully clicks Acknowledge or Accept Chat, the
currently playing page tune is stopped immediately instead of continuing to the
end of the WAV.

SECURITY
--------

* The public IceChat NX API requires the shared token.
* The Windows client requires HTTPS for remote BBS API URLs. Plain HTTP is
  accepted only for localhost/loopback testing.
* The Windows HTTP client does not follow redirects, preventing the IceChat NX
  token from being forwarded to a redirect target.
* The Windows client protects the saved API key with the current Windows user's
  DPAPI credentials. CONFIG/config.json contains api_token_protected rather
  than a reusable plaintext api_token after the client saves/migrates it.
* Existing plaintext Windows-client tokens are automatically migrated to DPAPI
  storage when v1.6.5 loads the configuration.
* ATDT must have its public base_url configured. The Admin Panel no longer
  constructs a security-sensitive API URL from Host or X-Forwarded-* headers.
* POST requests to api.php must use application/json and are limited to 64 KiB.
* data/doorstore/icechatnx and chatlogs are hardened to 0750 where supported;
  settings/state/transcript files are hardened to 0640 where supported.
* .htaccess allows external access only to api.php on Apache/LiteSpeed.
* Accept Chat validates the original ATDT session before bridging.
* The older X-SysopPager-Token header remains accepted only for migration.

WINDOWS COMMAND-LINE OPTIONS
----------------------------

  IceChatNX.exe --test-connection
  IceChatNX.exe --install-autostart
  IceChatNX.exe --remove-autostart
  IceChatNX.exe --minimized

VERSION
-------

IceChat NX v1.6.5
ATDT Native Door API: 1
Target: ATDT with native private SysOp chat support
Author/package: DOS BBS


ATDT ADMIN PANEL (v1.6.5)
=========================

After ATDT scans/registers the door, open Native Doors -> IceChat NX -> admin panel.
The panel provides:

  * Full IceChat NX API URL with Copy to clipboard.
  * Current API key, hidden by default, with Show/Hide and Copy to clipboard.
  * Generate new key. Rotating the key immediately invalidates the old key; update
    Windows clients with Link to BBS afterward.
  * SysOp display name, Windows-client offline threshold, caller page cooldown,
    offline page queueing, page retention, and chat-message retention.
  * Current Windows-client heartbeat/status and queue/chat summary.

Admin changes are stored in ATDT's private data/doorstore/icechatnx/settings.json
and override the release defaults in doors/icechatnx/config.php, so replacing the
door code during an upgrade does not erase those settings.

WINDOWS CLIENT OPTIONS (v1.6.5)
--------------------------------
The native Windows client now includes an Options menu on the top menu bar.

Chat Text Size
  Select 12, 14, 16, 18, 20, or 24 point terminal-style text. 16 pt is the
  default. Changes apply immediately to open chat windows and are saved in
  CONFIG\config.json.

Chat Background Color / SysOp Text Color / Caller Text Color / Input Text Color
  Opens the standard Windows color chooser. The default transcript palette is
  black background, cyan SysOp text, and green caller text; the message-entry
  field uses white text on the same black background. Colors apply immediately
  to open chat windows and persist in CONFIG\config.json.

Reset Chat Appearance
  Restores 16 pt text with the black/cyan/green terminal palette and white
  input text.

Auto Start with Windows
  Toggles the current user's Windows startup entry on or off. A check mark
  indicates that IceChat NX is currently configured to start with Windows.

Chat windows are dynamically resizable. The transcript, entry field, buttons, and status line automatically reflow when the window is resized.
