// The MIT License (MIT)
//
// Copyright (C) 2026 Scott Duensing
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
// IN THE SOFTWARE.

// hlpformat.h -- DVX Help binary file format structures
//
// Shared between the host-side help compiler and the DVX help viewer app.

#ifndef HLPFORMAT_H
#define HLPFORMAT_H

#include <stdint.h>
#include <stdbool.h>


// ---------------------------------------------------------------------------
// File magic and version
// ---------------------------------------------------------------------------

#define HLP_MAGIC   0x484C5044  // "HLPD" little-endian
#define HLP_VERSION 1


// ---------------------------------------------------------------------------
// Record types (HlpRecordHdrT.type)
// ---------------------------------------------------------------------------

#define HLP_REC_TEXT      0x01
#define HLP_REC_HEADING1  0x02
#define HLP_REC_HEADING2  0x03
#define HLP_REC_HEADING3  0x04
#define HLP_REC_IMAGE     0x05
#define HLP_REC_LINK      0x06
#define HLP_REC_LIST_ITEM 0x07
#define HLP_REC_TABLE     0x08
#define HLP_REC_HRULE     0x09
#define HLP_REC_NOTE      0x0A
#define HLP_REC_CODE      0x0B
#define HLP_REC_END       0xFF


// ---------------------------------------------------------------------------
// Note flags (HlpRecordHdrT.flags when type == HLP_REC_NOTE)
// ---------------------------------------------------------------------------

#define HLP_NOTE_INFO    0x00
#define HLP_NOTE_TIP     0x01
#define HLP_NOTE_WARNING 0x02

// Image alignment flags (HlpRecordHdrT.flags when type == HLP_REC_IMAGE)
// 0x00 = left (default, backward compatible with older .hlp files)
#define HLP_IMG_LEFT     0x00
#define HLP_IMG_CENTER   0x01
#define HLP_IMG_RIGHT    0x02


// ---------------------------------------------------------------------------
// TOC entry flags
// ---------------------------------------------------------------------------

#define HLP_TOC_EXPANDED 0x01


// ---------------------------------------------------------------------------
// File header (60 bytes, stored at EOF)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t magic;             // HLP_MAGIC
    uint32_t version;           // HLP_VERSION
    uint32_t topicCount;
    uint32_t topicDirOffset;    // absolute file offset
    uint32_t tocOffset;
    uint32_t tocCount;
    uint32_t indexOffset;
    uint32_t indexCount;
    uint32_t searchOffset;
    uint32_t searchSize;
    uint32_t stringTableOffset;
    uint32_t stringTableSize;
    uint32_t imagePoolOffset;
    uint32_t imagePoolSize;
    uint32_t defaultTopicStr;   // string table offset of default topic ID
} HlpHeaderT;


// ---------------------------------------------------------------------------
// Topic directory entry (20 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t topicIdStr;    // string table offset
    uint32_t titleStr;      // string table offset
    uint32_t contentOffset; // absolute file offset
    uint32_t contentSize;
    uint32_t reserved;
} HlpTopicDirT;


// ---------------------------------------------------------------------------
// Content record header (4 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint8_t  type;
    uint8_t  flags;
    uint16_t length;  // payload length (excluding this header)
} HlpRecordHdrT;


// ---------------------------------------------------------------------------
// Image reference (8 bytes, payload of HLP_REC_IMAGE)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t imageOffset;  // offset within image pool
    uint32_t imageSize;    // BMP data size
} HlpImageRefT;


// ---------------------------------------------------------------------------
// TOC entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t titleStr;   // string table offset
    uint16_t topicIdx;   // index into topic directory (0xFFFF = no topic)
    uint8_t  depth;      // nesting depth (0 = root)
    uint8_t  flags;      // HLP_TOC_EXPANDED
} HlpTocEntryT;


// ---------------------------------------------------------------------------
// Keyword index entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t keywordStr;  // string table offset
    uint16_t topicIdx;    // index into topic directory
    uint16_t reserved;
} HlpIndexEntryT;


// ---------------------------------------------------------------------------
// Search index -- trigram entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint8_t  trigram[3];
    uint8_t  postingCount;
    uint32_t postingOffset;  // byte offset within search section to uint16_t[] posting list
} HlpTrigramEntryT;


// ---------------------------------------------------------------------------
// Search section header
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t trigramCount;
    // followed by HlpTrigramEntryT[trigramCount]
    // followed by uint16_t posting lists
} HlpSearchHeaderT;


#endif // HLPFORMAT_H
