src/flat-html-generator.lua

7local function setup_dir_path(provided_dir)

8 if provided_dir then

9 return provided_dir

10 end

11 return "/mnt/mtwo/programming/ai-stuff/neocities-modernization"

117local FONT_STYLE = [[

118<style>

119body, pre {

120 font-family: 'Hack Nerd Font', 'Hack', 'Fira Code', 'JetBrains Mono',

121 'Cascadia Code', 'Consolas', 'Monaco', 'Liberation Mono',

122 'Courier New', monospace;

123}

124/* True page-centering for the poem column. The old <table align="center">

125 shrink-wrapped to its WIDEST line -- and an attached image (up to 800px) is

126 wider than the ~84-char text frame, so the cell stretched and the frames

127 hugged the left of that wide cell, landing the whole column left-of-center.

128 Fix: the cell centers its children, each <pre> is an inline-block that

129 centers as a block (text stays left-aligned inside), and media centers via

130 auto margins. Now a vertical line down the page bisects every poem AND image,

131 regardless of how wide any single image is. */

132td { text-align: center; }

133pre { display: inline-block; text-align: left; margin: 0 auto; }

134img, video, audio { margin-left: auto; margin-right: auto; }

135</style>

136]]

200local function load_layout_from_config()

201 local layout = unified_config.layout

202 if not layout then return end

204 -- Override LAYOUT values from config

205 if layout.regular_poem_width then LAYOUT.REGULAR_POEM_WIDTH = layout.regular_poem_width end

206 if layout.golden_poem_width then LAYOUT.GOLDEN_POEM_WIDTH = layout.golden_poem_width end

207 if layout.text_content_width then LAYOUT.TEXT_CONTENT_WIDTH = layout.text_content_width end

208 if layout.left_box_width then

209 LAYOUT.REGULAR_LEFT_BOX_WIDTH = layout.left_box_width

210 LAYOUT.GOLDEN_LEFT_BOX_WIDTH = layout.left_box_width

211 end

212 if layout.right_box_width then

213 LAYOUT.REGULAR_RIGHT_BOX_WIDTH = layout.right_box_width

214 LAYOUT.GOLDEN_RIGHT_BOX_WIDTH = layout.right_box_width

215 end

216 if layout.gap_width then

217 LAYOUT.REGULAR_GAP_WIDTH = layout.gap_width

218 LAYOUT.GOLDEN_GAP_WIDTH = layout.gap_width

219 end

220 if layout.left_junction_pos then LAYOUT.REGULAR_LEFT_JUNCTION_POS = layout.left_junction_pos end

221 if layout.right_junction_pos then LAYOUT.REGULAR_RIGHT_JUNCTION_POS = layout.right_junction_pos end

239local function load_diversity_cache(model_name)

240 model_name = model_name or inference_config.get_selected_model()

241 local model_dir = model_name:gsub(":", "_")

242 -- Issue 10-054: diversity stays on disk (embeddings_dir_disk).

243 local cache_file = utils.embeddings_dir_disk(model_name) .. "/diversity_cache.json"

245 if not utils.file_exists(cache_file) then

246 error(string.format([[

247Diversity cache not found: %s

249The diversity cache is required for HTML generation.

250Generate it with: ./run.sh --generate-diversity

252This takes ~1 minute with GPU (or ~42 hours with CPU using --cpu-only).

253]], cache_file))

254 end

256 utils.log_info("Loading diversity cache from: " .. cache_file)

257 local cache_data = utils.read_json_file(cache_file)

259 if not cache_data then

260 error("Failed to parse diversity cache JSON file")

261 end

263 if not cache_data.sequences then

264 error("Diversity cache has invalid format (missing sequences table)")

265 end

267 DIVERSITY_CACHE = cache_data

268 return cache_data

275local function load_similarity_rankings_cache(model_name)

276 model_name = model_name or inference_config.get_selected_model()

277 local model_dir = model_name:gsub(":", "_")

278 -- Issue 10-054: similarity ranking cache is movable (embeddings_dir, RAM).

279 local cache_file = utils.embeddings_dir(model_name) .. "/similarity_rankings_cache.json"

281 if not utils.file_exists(cache_file) then

282 error(string.format([[

283Similarity rankings cache not found: %s

285The similarity rankings cache is required for fast HTML generation.

286Generate it with: ./run.sh --generate-similarity

288This is a post-processing step that pre-sorts similarity rankings.

289]], cache_file))

290 end

292 utils.log_info("Loading similarity rankings cache from: " .. cache_file)

293 local cache_data = utils.read_json_file(cache_file)

295 if not cache_data then

296 error("Failed to parse similarity rankings cache JSON file")

297 end

299 if not cache_data.rankings then

300 error("Similarity rankings cache has invalid format (missing rankings table)")

301 end

303 -- Count rankings (for logging)

304 local count = 0

305 for _ in pairs(cache_data.rankings) do count = count + 1 end

307 -- Validate cache is not empty (Issue: empty cache generated by standalone script)

308 if count == 0 then

309 error(string.format([[

310Similarity rankings cache is empty (0 poems): %s

312This usually means the cache was generated before similarity files existed,

313or the standalone script encountered a path issue.

315To fix, regenerate with: ./run.sh --generate-similarity --force

317This will regenerate both similarity files AND the rankings cache.

318]], cache_file))

319 end

321 SIMILARITY_RANKINGS_CACHE = cache_data

322 return cache_data

335local function media_href(path)

336 path = path or ""

337 local sub = path:match("input/images/(.+)$") or (path:match("([^/]+)$") or path)

338 return (sub:gsub("[^%w%-%._~/]", function(c)

339 return string.format("%%%02X", string.byte(c))

340 end))

353local media_flattening_done = false

355local function flatten_media_files(output_dir)

356 -- Skip if already done this session (idempotent)

357 if media_flattening_done then

358 return true

359 end

361 -- The configured image sources are the source of truth for where to

362 -- look. Each entry has an internal project-relative path (where the

363 -- sync script drops files) and may also have an external source path

364 -- (where the operator's actual files live on the wider file system).

365 -- We prefer the internal path when present, and fall back to the

366 -- external source so a configured-but-not-yet-synced entry still

367 -- contributes media. A configured entry that is missing from both

368 -- is a warning, not a fatal error — operators may legitimately

369 -- declare more sources than are populated at any given moment.

370 local sources_loader = require("sources-loader")

371 sources_loader.set_project_root(DIR)

372 local image_dirs = sources_loader.get_directories_with_external("images")

374 if not image_dirs or #image_dirs == 0 then

375 utils.log_warn("No image sources configured in sources.images.directories; skipping media flattening")

376 media_flattening_done = true

377 return true

378 end

380 local target_dir = output_dir .. "/media"

381 os.execute('mkdir -p "' .. target_dir .. '"')

383 local copied = 0

384 local skipped = 0

385 local errors = 0

386 local sources_used = 0

388 for _, dir in ipairs(image_dirs) do

389 -- sources-loader's resolve_path already returns an ABSOLUTE path (it

390 -- prepends the project root to relative config entries), so use dir.path

391 -- directly. Prepending DIR again produced a doubled "/root//root/..." path

392 -- that never resolved, so every source looked "missing" -- which the

393 -- mandatory-source check below then turned into a fatal stage-9 failure.

394 local internal_path = dir.path

395 local external_path = dir.external and dir.external.source or nil

396 local resolved_path = nil

398 local internal_test = io.open(internal_path, "r")

399 if internal_test then

400 internal_test:close()

401 resolved_path = internal_path

402 elseif external_path then

403 local external_test = io.open(external_path, "r")

404 if external_test then

405 external_test:close()

406 resolved_path = external_path

407 end

408 end

410 if not resolved_path then

411 -- Every configured image source is mandatory (the "optional" concept was

412 -- removed): a missing source means media we expected to ship is absent,

413 -- so we fail loudly here rather than silently skip it. Fix it by running

414 -- the sync/extraction that populates the path, or remove the source from

415 -- config.lua if it is genuinely gone.

416 error(string.format(

417 "Image source '%s' not found at internal '%s'%s -- every source is required; sync/extract it or remove it from config.lua",

418 dir.name or "(unnamed)",

419 dir.path or "(no path)",

420 external_path and (" or external '" .. external_path .. "'") or ""))

421 else

422 sources_used = sources_used + 1

424 -- Find every file under the resolved source and place it under

425 -- output/media/. TWO species, two layouts (must match media_href in

426 -- the renderers exactly, or the <img src> points at the wrong file):

427 -- * art sources (path .../input/images/<source>): keep

428 -- <source>/<subpath>, so two files that share a basename in

429 -- different subdirs (e.g. my-art/x.png and my-art/game-design/x.png)

430 -- stay distinct instead of one silently overwriting the other.

431 -- * everything else (Mastodon media, content-addressed hashes):

432 -- flatten to the bare basename -- already unique, and this

433 -- collapses the ~7-level Mastodon nesting.

434 -- No leading-^ anchor: dir.path is absolute (see above), so we match the

435 -- "input/images/<rest>" tail wherever it appears -- the same tail

436 -- media_href() extracts in the renderers, keeping the two layouts identical.

437 local ns_prefix = dir.path and dir.path:match("input/images/(.+)$") or nil

438 local find_cmd = string.format('find "%s" -type f', resolved_path)

439 local handle = io.popen(find_cmd)

440 if handle then

441 for source_path in handle:lines() do

442 -- this file's path within its own source dir (art subdirs kept)

443 local within = source_path:sub(#resolved_path + 2)

444 local target_sub

445 if ns_prefix then

446 target_sub = ns_prefix .. "/" .. within

447 else

448 target_sub = source_path:match("([^/]+)$")

449 end

450 if target_sub and target_sub ~= "" then

451 local target_path = target_dir .. "/" .. target_sub

452 local exists_check = io.open(target_path, "r")

453 if exists_check then

454 exists_check:close()

455 skipped = skipped + 1

456 else

457 -- create the subdirectory before copying (art paths

458 -- now nest one or more levels under output/media/)

459 local parent = target_path:match("^(.*)/[^/]+$")

460 if parent then os.execute('mkdir -p "' .. parent .. '"') end

461 local cp_cmd = string.format('cp "%s" "%s"', source_path, target_path)

462 local success = os.execute(cp_cmd)

463 if success == 0 or success == true then

464 copied = copied + 1

465 else

466 errors = errors + 1

467 utils.log_warn("Failed to copy: " .. source_path)

468 end

469 end

470 end

471 end

472 handle:close()

473 else

474 utils.log_warn("Could not scan image source: " .. resolved_path)

475 end

476 end

477 end

479 utils.log_info(string.format(

480 "Media flattening: %d sources used | %d copied, %d skipped, %d errors",

481 sources_used, copied, skipped, errors))

483 media_flattening_done = true

484 return errors == 0

492local pagination_config_loaded = false

494local function load_pagination_config()

495 -- Skip if already loaded (idempotent)

496 if pagination_config_loaded then

497 return PAGINATION_CONFIG

498 end

500 -- Load pagination settings from unified config

501 if unified_config.pagination then

502 for key, value in pairs(unified_config.pagination) do

503 if key ~= "_comment" and PAGINATION_CONFIG[key] ~= nil then

504 PAGINATION_CONFIG[key] = value

505 end

506 end

507 end

509 -- Load storage settings from unified config (Issue 8-020)

510 if unified_config.storage then

511 for key, value in pairs(unified_config.storage) do

512 if key ~= "_comment" and STORAGE_CONFIG[key] ~= nil then

513 STORAGE_CONFIG[key] = value

514 end

515 end

516 end

518 pagination_config_loaded = true

519 return PAGINATION_CONFIG

539local function compute_storage_max_pages(output_dir, num_poems)

540 local function popen_num(cmd)

541 local h = io.popen(cmd)

542 if not h then return nil end

543 local out = h:read("*a"); h:close()

544 return tonumber((out or ""):match("(%d+)"))

545 end

546 local function dir_bytes(path)

547 return popen_num(string.format("du -s --block-size=1 %q", path)) or 0

548 end

550 local sim_dir = output_dir .. "/similar"

551 local diff_dir = output_dir .. "/different"

552 local page_count = popen_num(string.format("find %q -maxdepth 1 -name '*.html' | wc -l", sim_dir)) or 0

553 if page_count == 0 or num_poems == 0 then

554 -- First build: nothing to measure yet. Fall back to the NATURAL maximum (every

555 -- other poem could fill pages), i.e. effectively uncapped, and warn. A finite

556 -- value keeps %d logging and the math.min() cap well-defined; the next build

557 -- measures real page sizes and applies the storage cap.

558 local per_page = PAGINATION_CONFIG.poems_per_page

559 local natural_max = math.max(1, math.ceil(num_poems / (per_page > 0 and per_page or 1)))

560 utils.log_warn("Storage page cap: no pages in " .. sim_dir .. " to measure -- "

561 .. "generating UNCAPPED this build (natural max " .. natural_max

562 .. " pages/poem); re-run to apply the measured cap.")

563 return natural_max

564 end

566 local sim_bytes = dir_bytes(sim_dir)

567 local avg_page = sim_bytes / page_count

568 local per_page_level = avg_page * num_poems * 2

569 local fixed = math.max(0, dir_bytes(output_dir) - sim_bytes - dir_bytes(diff_dir))

570 local budget = STORAGE_CONFIG.limit_gb * 1e9 -- decimal GB; conservative vs GiB

572 local max_pages = math.floor((budget - fixed) / per_page_level)

573 if max_pages < 1 then max_pages = 1 end

575 utils.log_info(string.format(

576 "Storage page cap (measured): %d page(s)/poem -- budget %dGB, fixed output %.1fGB, "

577 .. "%.0fKB/page x %d poems x 2 sides", max_pages, STORAGE_CONFIG.limit_gb,

578 fixed / 1e9, avg_page / 1000, num_poems))

579 return max_pages

586local function calculate_page_count(total_poems)

587 local poems_per_page = PAGINATION_CONFIG.poems_per_page

588 return math.ceil(total_poems / poems_per_page)

601local function parse_pages_specification(pages_spec, total_pages_possible)

602 -- Ensure pagination config is loaded

603 load_pagination_config()

605 -- Default: use minimum_pages from config

606 if not pages_spec or pages_spec == "" or pages_spec == "default" then

607 local pages = {}

608 for i = 1, PAGINATION_CONFIG.minimum_pages do

609 table.insert(pages, i)

610 end

611 return {pages = pages, is_all = false}

612 end

614 -- "all" means generate all pages up to max_pages_per_poem limit

615 if pages_spec == "all" then

616 return {pages = nil, is_all = true} -- nil means "generate all" in context

617 end

619 -- Single page number: "5" → {5}

620 local single_num = tonumber(pages_spec)

621 if single_num then

622 return {pages = {single_num}, is_all = false}

623 end

625 -- Range: "1-10" → {1,2,3,...,10}

626 local start_page, end_page = pages_spec:match("^(%d+)%-(%d+)$")

627 if start_page and end_page then

628 start_page = tonumber(start_page)

629 end_page = tonumber(end_page)

631 if start_page and end_page and start_page <= end_page then

632 local pages = {}

633 for i = start_page, end_page do

634 table.insert(pages, i)

635 end

636 return {pages = pages, is_all = false}

637 else

638 utils.log_error(string.format("Invalid page range: %s (start must be <= end)", pages_spec))

639 return {pages = {1}, is_all = false} -- Fallback to page 1

640 end

641 end

643 -- Invalid format - fallback to page 1

644 utils.log_error(string.format("Invalid --pages format: '%s'. Expected: 1, all, or 1-10", pages_spec))

645 return {pages = {1}, is_all = false}

653local function get_poems_for_page(sorted_poems, page_num)

654 local poems_per_page = PAGINATION_CONFIG.poems_per_page

655 local start_idx = ((page_num - 1) * poems_per_page) + 1

656 local end_idx = math.min(start_idx + poems_per_page - 1, #sorted_poems)

658 local page_poems = {}

659 for i = start_idx, end_idx do

660 if sorted_poems[i] then

661 table.insert(page_poems, sorted_poems[i])

662 end

663 end

665 return page_poems

675local function get_unique_poem_filename_id(poem)

676 local category = poem.category or "unknown"

677 local id = poem.id or 0

678 return string.format("%s-%04d", category, id)

690local function get_poem_anchor_id(poem)

691 local poem_index = poem.poem_index or 0

692 return string.format("poem-%d", poem_index)

699local function format_page_number(page_num)

700 local padding = PAGINATION_CONFIG.page_number_padding

701 return string.format("%0" .. padding .. "d", page_num)

711local function generate_page_filename(poem_id, page_num, page_type)

712 local padded_id = string.format("%04d", poem_id)

713 local padded_page = format_page_number(page_num)

714 return string.format("%s/%s-%s.html", page_type, padded_id, padded_page)

727local function generate_prev_next_navigation(current_page, total_pages, poem_id, page_type, total_corpus)

728 local nav_parts = {}

730 -- Calculate poem range for this page

731 local poems_per_page = PAGINATION_CONFIG.poems_per_page

732 local max_pages = PAGINATION_CONFIG.max_pages_per_poem

733 local start_poem = ((current_page - 1) * poems_per_page) + 1

734 local end_poem = math.min(current_page * poems_per_page, total_pages * poems_per_page)

736 -- Check if this is a storage-constrained last page

737 local is_storage_limited = (total_pages == max_pages) and (total_corpus and total_corpus > end_poem)

738 local poems_shown = end_poem

739 local poems_omitted = total_corpus and (total_corpus - poems_shown) or 0

741 -- Header line with page info

742 table.insert(nav_parts, "════════════════════════════════════════════════════════════════════════════════")

744 if page_type == "chronological" then

745 table.insert(nav_parts, string.format(" Page %d of %d │ Poems %d-%d",

746 current_page, total_pages, start_poem, end_poem))

747 else

748 local padded_id = string.format("%04d", poem_id)

749 if is_storage_limited then

750 -- Show storage context on capped pages (Issue 8-020)

751 table.insert(nav_parts, string.format(" %s to Poem %s │ Page %d of %d │ Showing top %d poems",

752 page_type == "similar" and "Similar" or "Different",

753 padded_id, current_page, total_pages, poems_shown))

754 else

755 table.insert(nav_parts, string.format(" %s to Poem %s │ Page %d of %d │ Poems %d-%d",

756 page_type == "similar" and "Similar" or "Different",

757 padded_id, current_page, total_pages, start_poem, end_poem))

758 end

759 end

761 table.insert(nav_parts, "════════════════════════════════════════════════════════════════════════════════")

763 -- Storage constraint notice on last page (Issue 8-020)

764 if is_storage_limited and current_page == total_pages and poems_omitted > 0 then

765 table.insert(nav_parts, string.format(" (%d additional poems omitted for storage constraints)",

766 poems_omitted))

767 end

769 table.insert(nav_parts, "")

771 -- Navigation links

772 local nav_line = ""

774 -- Previous link (left aligned)

775 if current_page > 1 then

776 local prev_file

777 if page_type == "chronological" then

778 -- Issue 8-039 Fix: Chronological pages now in subdirectory, use relative paths

779 prev_file = string.format("%s.html", format_page_number(current_page - 1))

780 else

781 prev_file = string.format("%s-%s.html", string.format("%04d", poem_id), format_page_number(current_page - 1))

782 end

783 nav_line = string.format("[<a href=\"%s\">◀ Previous Page</a>]", prev_file)

784 else

785 nav_line = "[◀ Previous Page]" -- Disabled

786 end

788 -- Calculate padding to push next link to right side

789 local padding = 80 - #nav_line - 16 -- 16 chars for next link

790 if padding < 0 then padding = 0 end

791 nav_line = nav_line .. string.rep(" ", padding)

793 -- Next link (right aligned)

794 if current_page < total_pages then

795 local next_file

796 if page_type == "chronological" then

797 -- Issue 8-039 Fix: Chronological pages now in subdirectory, use relative paths

798 next_file = string.format("%s.html", format_page_number(current_page + 1))

799 else

800 next_file = string.format("%s-%s.html", string.format("%04d", poem_id), format_page_number(current_page + 1))

801 end

802 nav_line = nav_line .. string.format("[<a href=\"%s\">Next Page ▶</a>]", next_file)

803 else

804 nav_line = nav_line .. "[Next Page ▶]" -- Disabled

805 end

807 table.insert(nav_parts, nav_line)

808 table.insert(nav_parts, "────────────────────────────────────────────────────────────────────────────────")

810 return table.concat(nav_parts, "\n")

816local cached_poem_colors = nil

818local function load_poem_colors()

819 -- Skip if already loaded (idempotent)

820 if cached_poem_colors then

821 return cached_poem_colors

822 end

824 local poem_colors_file = utils.embeddings_dir() .. "/poem_colors.json"

825 local poem_colors_data = utils.read_json_file(poem_colors_file)

827 if poem_colors_data and poem_colors_data.poem_colors then

828 -- Count actual entries dynamically (stored total_poems may be stale)

829 cached_poem_colors = poem_colors_data.poem_colors

830 return cached_poem_colors

831 else

832 utils.log_warn("Could not load poem colors, using mock colors")

833 cached_poem_colors = MOCK_POEM_COLORS

834 return cached_poem_colors

835 end

840local function get_file_creation_timestamp(file_path)

841 -- Use bash stat command to get file modification time (best approximation)

842 local cmd = string.format("stat -c %%Y '%s' 2>/dev/null", file_path)

843 local handle = io.popen(cmd)

844

845 if handle then

846 local result = handle:read("*a")

847 handle:close()

848

849 if result and result:match("^%d+") then

850 return tonumber(result:match("^%d+"))

851 end

852 end

853

854 return nil

859local function extract_post_date_from_poem(poem_data)

860 -- First, try to use the creation_date metadata field (if available)

861 local creation_date = poem_data.creation_date or (poem_data.metadata and poem_data.metadata.creation_date)

862 if creation_date then

863 -- Parse ISO 8601 format: "2023-04-20T05:22:03" or "2023-04-20T05:22:03Z"

864 local year, month, day, hour, min, sec = creation_date:match("(%d+)-(%d+)-(%d+)T(%d+):(%d+):(%d+)")

865 if year and month and day then

866 local parsed_time = os.time({

867 year = tonumber(year),

868 month = tonumber(month),

869 day = tonumber(day),

870 hour = tonumber(hour) or 0,

871 min = tonumber(min) or 0,

872 sec = tonumber(sec) or 0

873 })

874 if parsed_time then return parsed_time end

875 end

876

877 -- Fallback: try to extract just date part

878 year, month, day = creation_date:match("(%d+)-(%d+)-(%d+)")

879 if year and month and day then

880 local parsed_time = os.time({

881 year = tonumber(year),

882 month = tonumber(month),

883 day = tonumber(day),

884 hour = 0, min = 0, sec = 0

885 })

886 if parsed_time then return parsed_time end

887 end

888 end

889

890 -- Fallback: Look for date patterns in poem content (legacy logic)

891 local content = poem_data.content or ""

892

893 -- First, try to extract YYYY-MM-DD from the very beginning (processing artifact dates)

894 local year, month, day = content:match("^(%d%d%d%d)%-(%d%d)%-(%d%d)")

895 if year and month and day then

896 return os.time({year=tonumber(year), month=tonumber(month), day=tonumber(day)})

897 end

898

899 -- Try to extract date from first line (other patterns)

900 local date_line = content:match("^([^\n]+)")

901 if date_line then

902 -- MM/DD/YYYY format

903 local month, day, year = date_line:match("(%d%d)/(%d%d)/(%d%d%d%d)")

904 if month and day and year then

905 return os.time({year=tonumber(year), month=tonumber(month), day=tonumber(day)})

906 end

907

908 -- Month DD, YYYY format (like "april 16th 2023")

909 local month_name, day_num, year_num = date_line:match("(%w+)%s+(%d+)%w*%s+(%d%d%d%d)")

910 if month_name and day_num and year_num then

911 local month_map = {

912 january=1, february=2, march=3, april=4, may=5, june=6,

913 july=7, august=8, september=9, october=10, november=11, december=12

914 }

915 local month_num = month_map[month_name:lower()]

916 if month_num then

917 return os.time({year=tonumber(year_num), month=month_num, day=tonumber(day_num)})

918 end

919 end

920 end

921

922 -- Fallback to file creation time if available

923 if poem_data.filepath then

924 local timestamp = get_file_creation_timestamp(poem_data.filepath)

925 if timestamp then

926 return timestamp

927 end

928 end

929

930 -- Final fallback to poem ID as timestamp approximation

931 return poem_data.id or 0

936local function sort_poems_chronologically_by_dates(poems_data)

937 local sorted_poems = {}

938

939 -- Extract all poems with temporal sorting data

940 for i, poem in ipairs(poems_data.poems) do

941 if poem.id then

942 local post_timestamp = extract_post_date_from_poem(poem)

943 table.insert(sorted_poems, {

944 poem = poem,

945 timestamp = post_timestamp,

946 sort_key = post_timestamp,

947 original_index = i

948 })

949 end

950 end

951

952 -- Sort by actual temporal order

953 table.sort(sorted_poems, function(a, b)

954 -- If timestamps are equal, use original index as tiebreaker

955 if a.sort_key == b.sort_key then

956 return a.original_index < b.original_index

957 end

958 return a.sort_key < b.sort_key

959 end)

960

961 return sorted_poems

966local function calculate_chronological_progress(poem_id, total_poems)

967 -- Calculate percentage through chronological corpus

968 local progress_percentage = (poem_id / total_poems) * 100

970 return {

971 poem_id = poem_id,

972 total_poems = total_poems,

973 percentage = progress_percentage,

974 position = poem_id,

975 quartile = math.ceil(progress_percentage / 25)

976 }

984local function compute_chronological_mapping(poems_data, chrono_poems_per_page)

985 -- Sort chronologically (same as generate_chronological_index_with_navigation)

986 local sorted_poems = sort_poems_chronologically_by_dates(poems_data)

987 local total_poems = #sorted_poems

988 local total_pages = chrono_poems_per_page and math.ceil(total_poems / chrono_poems_per_page) or 1

990 -- Issue 8-045: Calculate timeline bounds for time-based progress

991 -- sorted_poems[i].timestamp contains Unix timestamp from extract_post_date_from_poem()

992 local first_timestamp = sorted_poems[1] and sorted_poems[1].timestamp or 0

993 local last_timestamp = sorted_poems[total_poems] and sorted_poems[total_poems].timestamp or 0

994 local timeline_span = last_timestamp - first_timestamp

995 -- Avoid division by zero if all poems have same timestamp

996 if timeline_span <= 0 then timeline_span = 1 end

998 -- Build mapping

999 local mapping = {}

1000 for position, poem_info in ipairs(sorted_poems) do

1001 local poem = poem_info.poem

1002 local poem_index = poem.poem_index

1003 if poem_index then

1004 local page_number = chrono_poems_per_page and math.ceil(position / chrono_poems_per_page) or 1

1005 -- Issue 8-045: Calculate timeline progress as percentage of time elapsed

1006 local poem_timestamp = poem_info.timestamp or first_timestamp

1007 local timeline_progress = ((poem_timestamp - first_timestamp) / timeline_span) * 100

1008 mapping[poem_index] = {

1009 position = position,

1010 page_number = page_number,

1011 total_poems = total_poems,

1012 total_pages = total_pages,

1013 timeline_progress = timeline_progress -- Issue 8-045: time-based progress

1014 }

1015 end

1016 end

1018 return mapping

1035function M.default_chrono_per_page()

1036 -- Pull config.lua's pagination overrides into PAGINATION_CONFIG first, so the

1037 -- default reflects the CONFIG FILE (where --chrono-per-page's default lives),

1038 -- not the bare source-table placeholder. Idempotent; safe to call anywhere.

1039 load_pagination_config()

1040 local value = PAGINATION_CONFIG.chronological_poems_per_page

1041 if not value then

1042 error("config is missing chronological_poems_per_page; chronological "

1043 .. "pagination size is required (pass --chrono-per-page or set it "

1044 .. "in the pagination config)")

1045 end

1046 return value

1051local function generate_progress_dashes(progress_info, color_name, is_golden, position, has_corner_boxes)

1052 -- For golden poems: 82 chars interior (+ 2 corners = 84 total)

1053 -- For regular poems: 83 chars total (positions 0-82)

1054 -- Golden poems have corner characters (╔/┐ or ╚/┘) that add 2 to the width,

1055 -- so interior needs to be 1 less to maintain 84-char total alignment

1056 local total_chars = is_golden and 82 or 83

1057 local progress_chars = math.floor((progress_info.percentage / 100) * total_chars)

1058 local remaining_chars = total_chars - progress_chars

1060 -- Get color information

1061 local hex_color = COLOR_CONFIG[color_name] or COLOR_CONFIG["gray"]

1063 -- For golden bottom borders with corner boxes, we need to insert junction characters

1064 -- Issue 8-055: Fixed junction positions to align ╧/┴ under ┐/┌ corners

1065 -- Junction positions in the 82-char interior (0-indexed):

1066 -- - Position 10: under "similar" box ┐ (same as regular poems)

1067 -- - Position 71: under "different" box ┌ (regular + 1 due to wider golden poem)

1068 local LEFT_JUNCTION_POS = 10 -- Same as regular: left box ┐ at position 10

1069 local RIGHT_JUNCTION_POS = 71 -- Regular + 1: right box ┌ at position 71 (golden is 1 char wider)

1071 -- Junction positions for regular poems (different from golden due to no outer walls)

1072 -- Regular corner boxes: ┌─────────┐ (11 chars) + 59 spaces + ┌───────────┐ (13 chars) = 83 chars

1073 -- Inner walls at positions 10 and 70 (0-indexed)

1074 local REGULAR_LEFT_JUNCTION_POS = 10

1075 local REGULAR_RIGHT_JUNCTION_POS = 70

1077 local visual_output

1078 if is_golden and position == "bottom" and has_corner_boxes then

1079 -- Build progress bar with junction characters inserted

1080 -- We need to construct the bar character by character to insert junctions at the right spots

1082 -- Determine which junction character to use at each position

1083 -- ╧ (U+2567) - up single and horizontal double (connects to ═) - COLORED

1084 -- ┴ (U+2534) - up and horizontal single (connects to ─) - UNCOLORED

1085 local left_in_progress = LEFT_JUNCTION_POS < progress_chars

1086 local right_in_progress = RIGHT_JUNCTION_POS < progress_chars

1088 -- Build colored junctions (╧ when in progress section)

1089 local left_junction

1090 if left_in_progress then

1091 left_junction = string.format('<font color="%s"><b>╧</b></font>', hex_color)

1092 else

1093 left_junction = "┴"

1094 end

1096 local right_junction

1097 if right_in_progress then

1098 right_junction = string.format('<font color="%s"><b>╧</b></font>', hex_color)

1099 else

1100 right_junction = "┴"

1101 end

1103 -- Build the progress section (colored ═) and remaining section (─)

1104 -- We need to split around the junction positions

1105 local segments = {}

1106 local current_pos = 0

1108 -- Helper to add a segment with proper coloring

1109 local function add_segment(start_pos, end_pos)

1110 if end_pos <= start_pos then return end

1111 local seg_len = end_pos - start_pos

1113 -- Determine how much of this segment is progress vs remaining

1114 local progress_in_seg = math.max(0, math.min(seg_len, progress_chars - start_pos))

1115 local remaining_in_seg = seg_len - progress_in_seg

1117 if progress_in_seg > 0 then

1118 table.insert(segments, string.format('<font color="%s"><b>%s</b></font>',

1119 hex_color, string.rep("═", progress_in_seg)))

1120 end

1121 if remaining_in_seg > 0 then

1122 table.insert(segments, string.rep("─", remaining_in_seg))

1123 end

1124 end

1126 -- Bugfix: this copy started at 0 and ended at total_chars, landing the

1127 -- left junction one column too far right (col 11) and the right one a

1128 -- dash short -- so the bottom bar did not line up under the nav-box

1129 -- corners. Start at 1 and end at total_chars+1 to match poem-bars (the

1130 -- word pages, which were correct): 9 dashes before the left junction so

1131 -- it sits at column 10, 11 after the right junction. Width is unchanged.

1132 -- Segment 1: corner ╚ is column 0, so the first dash runs 1..left junction

1133 add_segment(1, LEFT_JUNCTION_POS)

1134 -- Insert left junction (colored if ╧, plain if ┴)

1135 table.insert(segments, left_junction)

1137 -- Segment 2: from left junction + 1 to right junction (exclusive)

1138 add_segment(LEFT_JUNCTION_POS + 1, RIGHT_JUNCTION_POS)

1139 -- Insert right junction (colored if ╧, plain if ┴)

1140 table.insert(segments, right_junction)

1142 -- Segment 3: from right junction + 1 to the far corner (exclusive of ┘)

1143 add_segment(RIGHT_JUNCTION_POS + 1, total_chars + 1)

1145 local interior = table.concat(segments, "")

1146 -- Color the ╚ corner to match the progress bar

1147 local colored_corner = string.format('<font color="%s"><b>╚</b></font>', hex_color)

1148 visual_output = colored_corner .. interior .. "┘"

1150 elseif not is_golden and position == "bottom" and has_corner_boxes then

1151 -- Regular poem bottom border with corner characters and junctions connecting to corner boxes

1152 -- Structure: ╘ (pos 0) + progress bar + ┴/╧ (pos 10) + progress bar + ┴/╧ (pos 69) + progress bar + ┘ (pos 81)

1153 -- ╘ (U+2558) - up single and right double - closes left box, connects to ═ progress

1154 -- ┘ (U+2518) - light up and left - closes right box, connects to ─ remaining

1156 local left_in_progress = REGULAR_LEFT_JUNCTION_POS < progress_chars

1157 local right_in_progress = REGULAR_RIGHT_JUNCTION_POS < progress_chars

1159 -- Build colored junctions (╧ when in progress section, ┴ otherwise)

1160 local left_junction

1161 if left_in_progress then

1162 left_junction = string.format('<font color="%s"><b>╧</b></font>', hex_color)

1163 else

1164 left_junction = "┴"

1165 end

1167 local right_junction

1168 if right_in_progress then

1169 right_junction = string.format('<font color="%s"><b>╧</b></font>', hex_color)

1170 else

1171 right_junction = "┴"

1172 end

1174 -- Left corner ╘ - colored if progress > 0 (position 0 is always in progress section if any progress)

1175 local left_corner

1176 if progress_chars > 0 then

1177 left_corner = string.format('<font color="%s"><b>╘</b></font>', hex_color)

1178 else

1179 left_corner = "╘"

1180 end

1182 -- Right corner ┘ - always uncolored (position 82 is almost never in progress section)

1183 local right_corner = "┘"

1185 -- Build the progress bar with junctions

1186 local segments = {}

1188 -- Helper to add a segment with proper coloring

1189 -- Note: positions are now 1-80 since 0 and 81 are corner characters

1190 local function add_segment(start_pos, end_pos)

1191 if end_pos <= start_pos then return end

1192 local seg_len = end_pos - start_pos

1194 local progress_in_seg = math.max(0, math.min(seg_len, progress_chars - start_pos))

1195 local remaining_in_seg = seg_len - progress_in_seg

1197 if progress_in_seg > 0 then

1198 table.insert(segments, string.format('<font color="%s"><b>%s</b></font>',

1199 hex_color, string.rep("═", progress_in_seg)))

1200 end

1201 if remaining_in_seg > 0 then

1202 table.insert(segments, string.rep("─", remaining_in_seg))

1203 end

1204 end

1206 -- Start with left corner

1207 table.insert(segments, left_corner)

1209 -- Segment 1: from 1 to left junction (exclusive) - 9 chars

1210 add_segment(1, REGULAR_LEFT_JUNCTION_POS)

1211 table.insert(segments, left_junction)

1213 -- Segment 2: from left junction + 1 to right junction (exclusive) - 59 chars

1214 add_segment(REGULAR_LEFT_JUNCTION_POS + 1, REGULAR_RIGHT_JUNCTION_POS)

1215 table.insert(segments, right_junction)

1217 -- Segment 3: from right junction + 1 to end - 1 (exclusive of right corner) - 11 chars

1218 add_segment(REGULAR_RIGHT_JUNCTION_POS + 1, total_chars - 1)

1220 -- End with right corner

1221 table.insert(segments, right_corner)

1223 -- No padding needed - content has 1-space indent for alignment

1224 visual_output = table.concat(segments, "")

1226 elseif is_golden then

1227 -- Golden poem top border or bottom without corner boxes

1228 -- Create progress visualization using equals/dash distinction

1229 local progress_section = string.rep("═", progress_chars)

1230 local remaining_section = string.rep("─", remaining_chars)

1232 local colored_progress = string.format(

1233 '<font color="%s"><b>%s</b></font>%s',

1234 hex_color, progress_section, remaining_section

1235 )

1237 -- Color the left corners to match the progress bar

1238 local colored_top_corner = string.format('<font color="%s"><b>╔</b></font>', hex_color)

1239 local colored_bottom_corner = string.format('<font color="%s"><b>╚</b></font>', hex_color)

1241 if position == "top" then

1242 visual_output = colored_top_corner .. colored_progress .. "┐"

1243 elseif position == "bottom" then

1244 visual_output = colored_bottom_corner .. colored_progress .. "┘"

1245 else

1246 visual_output = colored_top_corner .. colored_progress .. "┐"

1247 end

1248 else

1249 -- Regular poems: no padding needed - content has 1-space indent for alignment

1250 local progress_section = string.rep("═", progress_chars)

1251 local remaining_section = string.rep("─", remaining_chars)

1253 local colored_progress = string.format(

1254 '<font color="%s"><b>%s</b></font>%s',

1255 hex_color, progress_section, remaining_section

1256 )

1257 visual_output = colored_progress

1258 end

1260 -- Screen reader accessible version - brief format for frequent use

1261 local screen_reader_text

1262 if is_golden then

1263 screen_reader_text = string.format(

1264 'aria-label="golden poem border. %s."',

1265 color_name

1266 )

1267 else

1268 screen_reader_text = string.format(

1269 'aria-label="eighty dashes. %s."',

1270 color_name

1271 )

1272 end

1274 return {

1275 visual = visual_output,

1276 accessibility = screen_reader_text,

1277 raw_progress = progress_chars,

1278 raw_remaining = remaining_chars,

1279 color = color_name,

1280 percentage = progress_info.percentage,

1281 is_golden = is_golden or false

1282 }

1287local function wrap_single_line_80_chars(line)

1288 -- Wrap a single line to 80 characters, preserving words

1289 if #line <= 80 then

1290 return line

1291 end

1293 local result_lines = {}

1294 local words = {}

1296 for word in line:gmatch("%S+") do

1297 table.insert(words, word)

1298 end

1300 local current_line = ""

1301 for _, word in ipairs(words) do

1302 if #current_line == 0 then

1303 current_line = word

1304 elseif #current_line + 1 + #word <= 80 then

1305 current_line = current_line .. " " .. word

1306 else

1307 table.insert(result_lines, current_line)

1308 current_line = word

1309 end

1310 end

1312 if #current_line > 0 then

1313 table.insert(result_lines, current_line)

1314 end

1316 return table.concat(result_lines, "\n")

1321local function strip_html_tags(content)

1322 -- Strip all HTML tags and decode HTML entities for TXT export

1323 -- Images should be converted with render_attachment_images_txt() separately

1324 local result = content

1326 -- Strip HTML tags

1327 result = result:gsub("<[^>]+>", "")

1329 -- Decode common HTML entities

1330 result = result:gsub("&amp;", "&")

1331 result = result:gsub("&lt;", "<")

1332 result = result:gsub("&gt;", ">")

1333 result = result:gsub("&quot;", '"')

1334 result = result:gsub("&#39;", "'")

1335 result = result:gsub("&nbsp;", " ")

1336 result = result:gsub("&#(%d+);", function(n)

1337 return string.char(tonumber(n))

1338 end)

1340 -- Normalize multiple consecutive spaces/newlines

1341 result = result:gsub("[ \t]+", " ")

1342 result = result:gsub("\n[ \t]+", "\n")

1343 result = result:gsub("[ \t]+\n", "\n")

1344 result = result:gsub("\n\n\n+", "\n\n")

1346 return result

1351local function wrap_text_80_chars(text)

1352 -- Wrap text to 80 chars while preserving existing newlines (paragraph breaks)

1353 local input_lines = {}

1354 for line in (text .. "\n"):gmatch("(.-)\n") do

1355 table.insert(input_lines, line)

1356 end

1358 local output_lines = {}

1359 for _, line in ipairs(input_lines) do

1360 if #line == 0 then

1361 -- Preserve empty lines (paragraph breaks)

1362 table.insert(output_lines, "")

1363 else

1364 -- Wrap long lines

1365 local wrapped = wrap_single_line_80_chars(line)

1366 for wrapped_line in (wrapped .. "\n"):gmatch("(.-)\n") do

1367 table.insert(output_lines, wrapped_line)

1368 end

1369 end

1370 end

1372 return table.concat(output_lines, "\n")

1380function M.generate_similarity_ranked_list(starting_poem_id, poems_data, similarity_data)

1381 -- Verify cache is loaded

1382 if not SIMILARITY_RANKINGS_CACHE then

1383 error("Similarity rankings cache not loaded! Run: ./run.sh --generate-similarity")

1384 end

1386 if not SIMILARITY_RANKINGS_CACHE.rankings then

1387 error("Similarity rankings cache has invalid format (missing rankings table)")

1388 end

1390 -- Look up pre-sorted ranking for this poem

1391 local cached_ranking = SIMILARITY_RANKINGS_CACHE.rankings[tostring(starting_poem_id)]

1392 if not cached_ranking then

1393 error(string.format("Similarity ranking not found for poem %s in cache.", starting_poem_id))

1394 end

1396 -- Build poem index lookup for fast access

1397 local poem_by_index = {}

1398 for i, poem in ipairs(poems_data.poems) do

1399 if poem.poem_index then

1400 poem_by_index[poem.poem_index] = poem

1401 end

1402 end

1404 -- Initialize ranked list with starting poem

1405 local ranked_poems = {}

1406 local starting_poem = poems_data.poems[starting_poem_id]

1407 table.insert(ranked_poems, {

1408 id = starting_poem_id,

1409 poem = starting_poem,

1410 similarity = 1.0, -- Perfect similarity to self

1411 rank = 1

1412 })

1414 -- Add poems in pre-sorted order from cache

1415 -- Cache contains poem indices already sorted by similarity (descending)

1416 local rank = 2

1417 for _, target_poem_index in ipairs(cached_ranking) do

1418 local poem = poem_by_index[target_poem_index]

1419 if poem then

1420 table.insert(ranked_poems, {

1421 id = poem.id,

1422 poem = poem,

1423 similarity = nil, -- Not needed for display, saves memory

1424 rank = rank

1425 })

1426 rank = rank + 1

1427 end

1428 end

1430 return ranked_poems

1437function M.generate_maximum_diversity_sequence(starting_poem_id, poems_data, embeddings_data)

1438 -- Verify cache is loaded

1439 if not DIVERSITY_CACHE then

1440 error("Diversity cache not loaded! Run: ./run.sh --generate-diversity")

1441 end

1443 if not DIVERSITY_CACHE.sequences then

1444 error("Diversity cache has invalid format (missing sequences table)")

1445 end

1447 -- Look up pre-computed sequence

1448 local cached_sequence = DIVERSITY_CACHE.sequences[tostring(starting_poem_id)]

1449 if not cached_sequence then

1450 error(string.format("Diversity sequence not found for poem %d in cache. Cache may be corrupted or incomplete.", starting_poem_id))

1451 end

1453 -- Convert cached poem_index values to full poem objects

1454 -- Note: The diversity cache stores poem_index (globally unique), NOT poem.id (per-category)

1455 local diversity_sequence = {}

1456 local poem_lookup = {}

1458 -- Build lookup table keyed by poem_index (NOT poem.id which is per-category)

1459 for i, poem in ipairs(poems_data.poems) do

1460 if poem.poem_index then

1461 poem_lookup[poem.poem_index] = poem

1462 end

1463 end

1465 -- Convert cached sequence (contains poem_index values) to format expected by HTML generator

1466 -- Issue 10-025: Skip anchor poem (GPU cache stores source poem as first entry)

1467 for step, poem_index in ipairs(cached_sequence) do

1468 if poem_index ~= starting_poem_id then

1469 local poem = poem_lookup[poem_index]

1470 if poem then

1471 table.insert(diversity_sequence, {

1472 id = poem_index, -- Store poem_index for consistency

1473 poem = poem,

1474 step = step

1475 })

1476 end

1477 end

1478 end

1480 return diversity_sequence

1487local function render_attachment_images(attachments)

1488 -- Render HTML for poem attachments (images, audio, video)

1489 -- Returns empty string if no attachments or no renderable attachments

1490 -- Media output format designed for 80-char width aesthetic

1491 --

1492 -- ATTACHMENT STRUCTURE (from ActivityPub extraction):

1493 -- {

1494 -- media_type = "image/png" or "audio/mpeg" or "video/mp4",

1495 -- url = "https://server.com/media/files/123/456/original/abc.png",

1496 -- relative_path = "files/123/456/original/abc.png",

1497 -- alt_text = "User description" or nil,

1498 -- width = 1920, -- images/video only

1499 -- height = 1080 -- images/video only

1500 -- }

1502 if not attachments or #attachments == 0 then

1503 return ""

1504 end

1506 local media_html = {}

1507 -- "up to the site root" -- these attachments render on poem pages, which sit

1508 -- one level below output/ (output/similar/, output/different/, ...), so a

1509 -- "../" prefix reaches the root. Document-relative: resolves the same opened

1510 -- locally from any folder or served on the site, so no path conversion step.

1511 local base_path = ".."

1513 for _, attachment in ipairs(attachments) do

1514 local media_type = attachment.media_type or ""

1515 -- Issue 8-048: media lives at output/media/<source>/<subpath> (see

1516 -- flatten_media_files); media_href keeps art's source+subdir structure so

1517 -- same-named pieces don't collide. "../media/" reaches it from a poem page.

1518 local relative_path = attachment.relative_path or ""

1519 -- media_href namespaces art by source+subdir (collision-safe) and

1520 -- url-encodes; Mastodon hashes collapse to the bare name. Matches where

1521 -- flatten_media_files placed the file.

1522 local media_src = base_path .. "/media/" .. media_href(relative_path)

1524 if media_type:match("^image/") then

1525 -- Use alt text if available, otherwise generate generic description

1526 -- Issue 9-012: ActivityPub uses 'description' field for alt-text

1527 local alt_text = attachment.description or attachment.alt_text or "Image attachment"

1528 -- Issue 8-053: Normalize newlines to spaces for clean HTML attributes

1529 alt_text = alt_text:gsub("\n", " "):gsub("\r", "")

1530 -- Escape quotes in alt text for HTML attribute

1531 alt_text = alt_text:gsub('"', '&quot;')

1533 -- Build image tag with lazy loading for performance

1534 -- Issue 8-005 Fix: Add max-width to prevent viewport overflow

1535 -- display:block prevents multiple images from appearing side-by-side

1536 -- max-width:min(100%,800px) caps at content width (~80 chars) while being responsive

1537 -- width/height hints help browser reserve space before load (aspect ratio preserved)

1538 -- Issue 8-053: title attribute provides mouse-over tooltip for sighted users

1539 local img_tag

1540 if attachment.width and attachment.height then

1541 img_tag = string.format(

1542 ' <img src="%s" alt="%s" title="%s" loading="lazy" width="%d" height="%d" style="display:block; max-width:min(100%%,800px); height:auto">',

1543 media_src, alt_text, alt_text, attachment.width, attachment.height

1544 )

1545 else

1546 img_tag = string.format(

1547 ' <img src="%s" alt="%s" title="%s" loading="lazy" style="display:block; max-width:min(100%%,800px); height:auto">',

1548 media_src, alt_text, alt_text

1549 )

1550 end

1551 table.insert(media_html, img_tag)

1553 elseif media_type:match("^audio/") then

1554 -- Issue 8-049: Audio playback support

1555 -- controls: Shows play/pause, volume, seek bar

1556 -- preload="metadata": Only loads duration/metadata initially for performance

1557 local audio_tag = string.format(

1558 ' <audio controls preload="metadata" style="display:block; max-width:100%%">\n' ..

1559 ' <source src="%s" type="%s">\n' ..

1560 ' Your browser does not support the audio element.\n' ..

1561 ' </audio>',

1562 media_src, media_type

1563 )

1564 table.insert(media_html, audio_tag)

1566 elseif media_type:match("^video/") then

1567 -- Issue 8-049: Video playback support

1568 -- controls: Shows play/pause, volume, seek bar, fullscreen

1569 -- preload="metadata": Only loads poster frame initially for performance

1570 -- max-width caps at content width while being responsive

1571 local video_tag

1572 if attachment.width and attachment.height then

1573 video_tag = string.format(

1574 ' <video controls preload="metadata" width="%d" height="%d" style="display:block; max-width:min(100%%,800px); height:auto">\n' ..

1575 ' <source src="%s" type="%s">\n' ..

1576 ' Your browser does not support the video element.\n' ..

1577 ' </video>',

1578 attachment.width, attachment.height, media_src, media_type

1579 )

1580 else

1581 video_tag = string.format(

1582 ' <video controls preload="metadata" style="display:block; max-width:min(100%%,800px); height:auto">\n' ..

1583 ' <source src="%s" type="%s">\n' ..

1584 ' Your browser does not support the video element.\n' ..

1585 ' </video>',

1586 media_src, media_type

1587 )

1588 end

1589 table.insert(media_html, video_tag)

1590 end

1591 end

1593 if #media_html == 0 then

1594 return ""

1595 end

1597 -- Issue 8-005 Fix: Close </pre> before media, reopen after

1598 -- Media inside <pre> don't respect max-width:100% because <pre> sizes to content

1599 -- By closing </pre>, media inherit width constraints from the parent <td> container

1600 return "\n</pre>\n" .. table.concat(media_html, "\n") .. "\n<pre>\n"

1606local function render_attachment_images_txt(attachments)

1607 -- Render plain text placeholders for poem attachments (images, audio, video)

1608 -- Returns [Image: alt-text], [Audio: filename], [Video: filename] format for TXT export

1609 -- Unlike render_attachment_images(), this outputs plain text, not HTML

1610 --

1611 -- This function exists because TXT exports cannot contain HTML media tags.

1612 -- Media are replaced with bracketed descriptions.

1614 if not attachments or #attachments == 0 then

1615 return ""

1616 end

1618 local media_lines = {}

1620 for _, attachment in ipairs(attachments) do

1621 local media_type = attachment.media_type or ""

1622 local placeholder

1624 if media_type:match("^image/") then

1625 -- Use alt text if available, otherwise indicate no description

1626 local alt_text = attachment.description or attachment.alt_text or "no description"

1627 placeholder = string.format("[Image: %s]", alt_text)

1629 elseif media_type:match("^audio/") then

1630 -- Issue 8-049: Audio placeholder

1631 local basename = (attachment.relative_path or ""):match("([^/]+)$") or "audio file"

1632 placeholder = string.format("[Audio: %s]", basename)

1634 elseif media_type:match("^video/") then

1635 -- Issue 8-049: Video placeholder

1636 local basename = (attachment.relative_path or ""):match("([^/]+)$") or "video file"

1637 placeholder = string.format("[Video: %s]", basename)

1638 end

1640 if placeholder then

1641 -- Wrap long text to 80 characters

1642 if #placeholder > 80 then

1643 placeholder = wrap_text_80_chars(placeholder)

1644 end

1645 table.insert(media_lines, placeholder)

1646 end

1647 end

1649 if #media_lines == 0 then

1650 return ""

1651 end

1653 -- Return with newline prefix/suffix for proper spacing

1654 return "\n" .. table.concat(media_lines, "\n") .. "\n"

1659local function format_warning_box(warning_text)

1660 -- Create simple ASCII box around content warning

1661 local content = wrap_text_80_chars(warning_text)

1662 local lines = {}

1663 for line in content:gmatch("[^\n]+") do

1664 table.insert(lines, line)

1665 end

1666

1667 -- Find longest line for box width

1668 local max_width = 0

1669 for _, line in ipairs(lines) do

1670 max_width = math.max(max_width, #line)

1671 end

1672

1673 -- Ensure minimum width and maximum of 76 chars (leave room for box borders)

1674 max_width = math.min(math.max(max_width, 20), 76)

1675

1676 local boxed = {}

1677 table.insert(boxed, "┌" .. string.rep("─", max_width + 2) .. "┐")

1678

1679 for _, line in ipairs(lines) do

1680 local padded = line .. string.rep(" ", max_width - #line)

1681 table.insert(boxed, "│ " .. padded .. " │")

1682 end

1683

1684 table.insert(boxed, "└" .. string.rep("─", max_width + 2) .. "┘")

1685

1686 return table.concat(boxed, "\n")

1691local function escape_html(text)

1692 -- Escape HTML special characters in poem content to prevent browser interpretation

1693 -- Issue 8-041: Fixes bug where poem content containing </pre> breaks page rendering

1694 -- IMPORTANT: Must be called BEFORE apply_markdown_formatting() so that

1695 -- markdown-generated HTML tags (like <em>) are NOT escaped

1696 -- Order matters: & must be escaped first, otherwise &lt; becomes &amp;lt;

1697 if not text then return "" end

1698 return text

1699 -- Strip NUL and other C0 control bytes that occasionally ride along in

1700 -- source poem text (a stray \0 in one post is what made a chronological

1701 -- page read as "binary" and could make a browser choke on it). Keep the

1702 -- legitimate whitespace controls: tab (\9), newline (\10), CR (\13).

1703 :gsub("[%z\1-\8\11\12\14-\31]", "")

1704 :gsub("&", "&amp;")

1705 :gsub("<", "&lt;")

1706 :gsub(">", "&gt;")

1711local function apply_markdown_formatting(text)

1712 -- Issue 4-003 (August 2026): emphasis renders styled AND keeps the typed

1713 -- delimiters visible ("both", per user) -- *love* shows as italic *love*.

1714 -- Delimiters already consumed into output are re-emitted as \1 sentinels

1715 -- so the narrower single-asterisk pass cannot re-match inside a bold span;

1716 -- escape_html strips control bytes beforehand, so \1 cannot collide with

1717 -- poem content. Sentinels become literal asterisks at the end.

1719 -- Handle *\*text*\* (legacy escaped-italics convention, kept first so the

1720 -- plain passes below never half-consume its backslash form)

1721 text = text:gsub("%*\\%*([^%*]+)%*\\%*", "<em>\1%1\1</em>")

1723 -- Handle **text** (bold) before *text* so the pair is not split in two

1724 text = text:gsub("%*%*([^%*]+)%*%*", "<strong>\1\1%1\1\1</strong>")

1726 -- Handle *text* (italics). The content must start and end on non-space

1727 -- and stay on one line: "2 * 3 * 4" and asterisk bullet lists are not

1728 -- emphasis. (Two passes because Lua patterns have no alternation: one

1729 -- for 2+ character spans, one for the single-character *x* case.)

1730 text = text:gsub("%*([^%s%*][^%*\n]-[^%s%*])%*", "<em>\1%1\1</em>")

1731 text = text:gsub("%*([^%s%*])%*", "<em>\1%1\1</em>")

1733 -- Handle ~~text~~ (strikethrough) and `text` (inline code)

1734 text = text:gsub("~~([^~]+)~~", "<del>~~%1~~</del>")

1735 text = text:gsub("`([^`\n]+)`", "<code>`%1`</code>")

1737 -- Sentinels back to the asterisks the author typed

1738 text = text:gsub("\1", "*")

1740 return text

1745local function is_golden_poem(poem)

1746 -- Issue 8-044: Use pre-calculated golden status from extraction metadata

1747 -- This correctly accounts for:

1748 -- - Pre-anonymization content (original @mentions preserved)

1749 -- - Content warning text (without "CW: " prefix)

1750 -- The extraction calculates this once; we use metadata as single source of truth

1751 if poem.metadata and poem.metadata.is_golden_poem then

1752 return true

1753 end

1754 return false

1759local function is_boost_poem(poem)

1760 -- Issue 8-057: Detect boosted/shared posts for visual formatting

1761 -- Boosts are reshared content from other fediverse users

1762 -- boost_type can be: "cached_external", "external", or "embedded"

1763 if poem.metadata and poem.metadata.is_boost then

1764 return true

1765 end

1766 return false

1771local function get_poem_display_filename(poem)

1772 -- Returns the display filename for a poem (without extension)

1773 -- For notes: uses metadata.source_file (the original filename)

1774 -- For fediverse/messages: uses the numeric ID

1775 -- All categories: no .txt extension (cleaner display)

1776 local category = poem.category or "unknown"

1777 local filename

1779 if category == "notes" and poem.metadata and poem.metadata.source_file then

1780 -- Notes preserve their original descriptive filenames

1781 filename = poem.metadata.source_file

1782 else

1783 -- Fediverse and messages use numeric ID

1784 filename = tostring(poem.id or "unknown")

1785 end

1787 return category .. "/" .. filename

1792local function generate_corner_box_separator(hex_color)

1793 -- Generate the separator line with corner box tops for GOLDEN poems

1794 -- Format: ╟─────────┐ ┌───────────┤

1795 -- Left box: 11 chars (╟ + 9×─ + ┐)

1796 -- Right box: 13 chars (┌ + 11×─ + ┤)

1797 -- Gap: 60 chars (spaces)

1798 -- Total: 84 chars

1799 -- The left junction ╟ is colored to match the progress bar

1800 local colored_junction = string.format('<font color="%s"><b>╟</b></font>', hex_color)

1801 local left_box = colored_junction .. string.rep("─", 9) .. "┐"

1802 local right_box = "┌" .. string.rep("─", 11) .. "┤"

1803 local gap = string.rep(" ", 60)

1804 return left_box .. gap .. right_box

1810local function colorize_char(char, hex_color)

1811 if hex_color then

1812 return string.format('<font color="%s"><b>%s</b></font>', hex_color, char)

1813 end

1814 return char

1820local function generate_regular_corner_box_top(progress_chars, hex_color)

1821 -- Generate the top line of corner boxes for REGULAR poems (no side walls)

1822 -- Format: ┌─────────┐ ┌───────────┐

1823 -- Left box: 11 chars (┌ + 9×─ + ┐) at positions 0-10

1824 -- Right box: 13 chars (┌ + 11×─ + ┐) at positions 70-82

1825 -- Gap: 59 chars (spaces) at positions 11-69

1826 -- Total: 83 chars

1828 progress_chars = progress_chars or 0

1830 -- Left box (positions 0-10)

1831 local left_parts = {}

1832 -- Position 0: ┌

1833 table.insert(left_parts, progress_chars > 0 and colorize_char("┌", hex_color) or "┌")

1834 -- Positions 1-9: ─────────

1835 for i = 1, 9 do

1836 table.insert(left_parts, progress_chars > i and colorize_char("─", hex_color) or "─")

1837 end

1838 -- Position 10: ┐

1839 table.insert(left_parts, progress_chars > 10 and colorize_char("┐", hex_color) or "┐")

1841 -- Gap (positions 11-69) - spaces don't need coloring

1842 local gap = string.rep(" ", 59)

1844 -- Right box (positions 70-82)

1845 local right_parts = {}

1846 -- Position 70: ┌

1847 table.insert(right_parts, progress_chars > 70 and colorize_char("┌", hex_color) or "┌")

1848 -- Positions 71-81: ───────────

1849 for i = 71, 81 do

1850 table.insert(right_parts, progress_chars > i and colorize_char("─", hex_color) or "─")

1851 end

1852 -- Position 82: ┐

1853 table.insert(right_parts, progress_chars > 82 and colorize_char("┐", hex_color) or "┐")

1855 return table.concat(left_parts) .. gap .. table.concat(right_parts)

1860local function generate_regular_corner_box_bottom()

1861 -- Generate the bottom line of corner boxes for REGULAR poems

1862 -- Format: └─────────┘ └───────────┘

1863 -- Gap: 59 chars, Total: 83 chars

1864 local left_box = "└" .. string.rep("─", 9) .. "┘"

1865 local right_box = "└" .. string.rep("─", 11) .. "┘"

1866 local gap = string.rep(" ", 59)

1867 return left_box .. gap .. right_box

1872local function generate_corner_box_nav_line(similar_link, different_link, chronological_link, hex_color)

1873 -- Generate the navigation line with corner box walls for GOLDEN poems (Issue 8-030)

1874 -- Format: ║ similar │ chronological │ different │

1875 -- Left box: ║ + space + link + space + │ = 11 chars

1876 -- Center text: chronological (13 chars visible) - or empty space if nil (on chronological.html)

1877 -- Right box: │ + space + link + space + │ = 13 chars

1878 -- Gaps: 2 gaps of ~23 chars each

1879 -- Total: 84 chars

1880 -- The left wall ║ is colored to match the progress bar

1882 -- The links contain HTML, so we need to measure visible text

1883 local similar_visible = similar_link:gsub("<[^>]+>", "") -- "similar"

1884 local different_visible = different_link:gsub("<[^>]+>", "") -- "different"

1886 -- Handle nil chronological_link (on chronological.html page, we don't show this link)

1887 local center_text = ""

1888 local center_visible_len = 0

1889 if chronological_link then

1890 center_text = chronological_link

1891 center_visible_len = chronological_link:gsub("<[^>]+>", ""):len() -- "chronological" = 13 chars

1892 end

1894 -- Left box: ║ (colored) + space + similar + padding + │

1895 local colored_wall = string.format('<font color="%s"><b>║</b></font>', hex_color)

1896 local left_content_width = 9 -- space between ║ and │

1897 local similar_padding = left_content_width - 1 - #similar_visible -- 1 for leading space

1898 local left_box = colored_wall .. " " .. similar_link .. string.rep(" ", similar_padding) .. "│"

1900 -- Right box: │ + space + different + padding + │

1901 local right_content_width = 11 -- space between │ and │

1902 local different_padding = right_content_width - 1 - #different_visible -- 1 for leading space

1903 local right_box = "│ " .. different_link .. string.rep(" ", different_padding) .. "│"

1905 -- Calculate gaps: Total 84 - 11 (left) - center_visible - 13 (right) = remaining

1906 -- If no center text, distribute all 47+13 = 60 chars into the gaps (30 left, 30 right)

1907 -- If center text (13 chars), split remaining 47 into 22 left + 25 right

1908 local left_gap, right_gap

1909 if center_visible_len > 0 then

1910 left_gap = string.rep(" ", 22)

1911 right_gap = string.rep(" ", 25)

1912 else

1913 -- No chronological link - distribute 60 chars evenly (30+30)

1914 left_gap = string.rep(" ", 30)

1915 right_gap = string.rep(" ", 30)

1916 end

1918 return left_box .. left_gap .. center_text .. right_gap .. right_box

1924local function generate_regular_corner_box_nav_line(similar_link, different_link, chronological_link, progress_chars, hex_color)

1925 -- Generate the navigation line with corner box walls for REGULAR poems (Issue 8-030)

1926 -- Format: │ similar │ chronological │ different │

1927 -- Left box: │ + space + link + space + │ = 11 chars (positions 0-10)

1928 -- Center text: chronological (13 chars visible) - or empty space if nil (on chronological.html)

1929 -- Right box: │ + space + link + space + │ = 13 chars (positions 70-82)

1930 -- Gaps: 2 gaps totaling 59 chars (with 13 char center text: 23 left + 23 right)

1931 -- Total: 83 chars

1933 progress_chars = progress_chars or 0

1935 local similar_visible = similar_link:gsub("<[^>]+>", "")

1936 local different_visible = different_link:gsub("<[^>]+>", "")

1938 -- Handle nil chronological_link (on chronological.html page, we don't show this link)

1939 local center_text = ""

1940 local center_visible_len = 0

1941 if chronological_link then

1942 center_text = chronological_link

1943 center_visible_len = chronological_link:gsub("<[^>]+>", ""):len() -- "chronological" = 13 chars

1944 end

1946 -- Left box: │ + space + similar + padding + │

1947 -- Wall characters at positions 0 and 10

1948 local left_wall = progress_chars > 0 and colorize_char("│", hex_color) or "│"

1949 local right_wall_of_left = progress_chars > 10 and colorize_char("│", hex_color) or "│"

1950 local left_content_width = 9

1951 local similar_padding = left_content_width - 1 - #similar_visible

1952 local left_box = left_wall .. " " .. similar_link .. string.rep(" ", similar_padding) .. right_wall_of_left

1954 -- Right box: │ + space + different + padding + │

1955 -- Wall characters at positions 70 and 82

1956 local left_wall_of_right = progress_chars > 70 and colorize_char("│", hex_color) or "│"

1957 local right_wall = progress_chars > 82 and colorize_char("│", hex_color) or "│"

1958 local right_content_width = 11

1959 local different_padding = right_content_width - 1 - #different_visible

1960 local right_box = left_wall_of_right .. " " .. different_link .. string.rep(" ", different_padding) .. right_wall

1962 -- Calculate gaps: Total 83 - 11 (left) - 13 (right) = 59 for gaps + center

1963 -- If no center text, distribute 59 chars into the gaps (29 left, 30 right)

1964 -- If center text (13 chars), split remaining 46 into 23 left + 23 right

1965 local left_gap, right_gap

1966 if center_visible_len > 0 then

1967 left_gap = string.rep(" ", 23)

1968 right_gap = string.rep(" ", 23)

1969 else

1970 -- No chronological link - distribute 59 chars (29+30)

1971 left_gap = string.rep(" ", 29)

1972 right_gap = string.rep(" ", 30)

1973 end

1975 return left_box .. left_gap .. center_text .. right_gap .. right_box

1980local function apply_golden_poem_formatting(content, is_golden, similar_link, different_link, chronological_link, hex_color)

1981 -- Golden poem side borders: ║ on left (colored), │ on right

1982 -- Interior width: 80 characters for content (with 1 space padding on each side)

1983 -- Format: ║ + space + 80 chars content (padded) + space + │ = 84 total

1984 -- The left wall ║ is colored to match the progress bar

1985 if not is_golden then

1986 return content

1987 end

1989 local CONTENT_WIDTH = 80 -- Content area between padding spaces

1990 local color = hex_color or "#787878" -- Default to gray if no color provided

1992 -- Helper to count UTF-8 characters (not bytes)

1993 -- Box-drawing chars are 3 bytes each, so #str gives wrong count

1994 local function utf8_char_count(str)

1995 -- Remove UTF-8 continuation bytes (0x80-0xBF), count what remains

1996 return #(str:gsub("[\128-\191]", ""))

1997 end

1999 -- Split content into lines (append newline to handle last line without trailing newline)

2000 local lines = {}

2001 for line in (content .. "\n"):gmatch("(.-)\n") do

2002 table.insert(lines, line)

2003 end

2005 local formatted_lines = {}

2006 local colored_wall = string.format('<font color="%s"><b>║</b></font>', color)

2008 for _, line in ipairs(lines) do

2009 -- Calculate visible length (excluding HTML tags, counting UTF-8 chars)

2010 -- Issue 8-055: Also decode HTML entities for accurate width counting

2011 -- e.g., &gt; is 4 bytes but displays as 1 character (>)

2012 local visible_length = text_formatter.calculate_visible_width(line)

2014 -- Pad or handle line to fit content width

2015 local padded_line

2016 if visible_length >= CONTENT_WIDTH then

2017 -- Line is already at or over width - use as-is

2018 padded_line = line

2019 else

2020 -- Pad with spaces to reach content width

2021 local padding_needed = CONTENT_WIDTH - visible_length

2022 padded_line = line .. string.rep(" ", padding_needed)

2023 end

2025 -- Add side borders with padding: ║ (colored) content │

2026 table.insert(formatted_lines, colored_wall .. " " .. padded_line .. " │")

2027 end

2029 -- Add corner box navigation (separator + nav line) if links provided

2030 -- Issue 9-003 Fix: Only require similar and different links - chronological_link can be nil

2031 if similar_link and different_link then

2032 -- Add separator line with corner box tops: ╟─────────┐ ┌───────────┤

2033 table.insert(formatted_lines, generate_corner_box_separator(color))

2034 -- Add navigation line with corner box walls: ║ similar │ chronological │ different │

2035 -- chronological_link may be nil on chronological.html (shows empty space in center)

2036 table.insert(formatted_lines, generate_corner_box_nav_line(similar_link, different_link, chronological_link, color))

2037 end

2039 return table.concat(formatted_lines, "\n")

2069local function format_content_with_warnings(text, poem_category, poem, similar_link, different_link, chronological_link, hex_color)

2070 -- Issue 8-041: Escape HTML special characters in poem content FIRST

2071 -- This prevents browser from interpreting poem content as HTML markup

2072 -- (e.g., a poem containing "</pre>" would otherwise close the preformatted block)

2073 text = escape_html(text)

2075 -- Apply markdown formatting AFTER escaping

2076 -- This allows *italics* to become <em>italics</em> while keeping

2077 -- literal < > & in poem content safely escaped

2078 text = apply_markdown_formatting(text)

2080 -- Check if this is a golden poem

2081 local is_golden = poem and is_golden_poem(poem)

2083 local formatted_lines = {}

2085 -- Issue 9-011: Display content warning from poem.content_warning field (Mastodon CW)

2086 -- This is separate from in-content CW: patterns - it comes from ActivityPub summary field

2087 if poem and poem.content_warning and poem.content_warning ~= "" then

2088 local cw_label = "CW: " .. poem.content_warning

2089 local warning_box = format_warning_box(cw_label)

2090 table.insert(formatted_lines, warning_box)

2091 table.insert(formatted_lines, "") -- First newline

2092 table.insert(formatted_lines, "") -- Second newline for spacing

2093 end

2095 -- Detect additional content warning patterns in text (CW:, content warning:, etc.)

2096 -- Issue 10-021: Use text_formatter.format_poem_lines to preserve empty lines (paragraph breaks)

2097 local lines = text_formatter.format_poem_lines(text)

2099 for _, line in ipairs(lines) do

2100 -- Check if line starts with content warning (in-content CW pattern)

2101 if line:lower():match("^%s*cw%s*:") or line:lower():match("^%s*content warning%s*:") then

2102 -- Format content warning with box

2103 local warning_box = format_warning_box(line)

2104 table.insert(formatted_lines, warning_box)

2105 table.insert(formatted_lines, "") -- First newline

2106 table.insert(formatted_lines, "") -- Second newline for spacing

2107 else

2108 -- Issue 10-021: Wrap long lines while preserving leading whitespace

2109 -- This replaces 8-056's no-wrap approach with whitespace-aware wrapping

2110 local wrapped = text_formatter.wrap_preserving_indent(line, 80)

2111 for _, wrapped_line in ipairs(wrapped) do

2112 table.insert(formatted_lines, wrapped_line)

2113 end

2114 end

2115 end

2117 local formatted_content = table.concat(formatted_lines, "\n")

2119 -- Apply golden poem box-drawing formatting (with corner box nav inside)

2120 if is_golden then

2121 formatted_content = apply_golden_poem_formatting(formatted_content, true, similar_link, different_link, chronological_link, hex_color)

2122 else

2123 -- For regular poems, add 1-space left padding to each content line

2124 -- Content uses 1-space indent for alignment (83 chars total width)

2125 local padded_lines = {}

2126 for line in (formatted_content .. "\n"):gmatch("(.-)\n") do

2127 table.insert(padded_lines, " " .. line)

2128 end

2129 formatted_content = table.concat(padded_lines, "\n")

2130 end

2132 return formatted_content, is_golden

2145local function warn_chrono_fallback_once(reason)

2146 if chrono_fallback_warned then return end

2147 chrono_fallback_warned = true

2148 utils.log_warn(string.format(

2149 "chronological links fell back to chronological/index.html (%s) - " ..

2150 "the #poem anchor is lost across that redirect, so every link lands at " ..

2151 "the top of the chronological view instead of at its poem", reason))

2160local function format_single_poem_with_progress_and_color(poem, total_poems, poem_colors, chrono_mapping, chrono_paginated)

2161 -- Issue 9-013: a ranked IMAGE entry (pseudo-poem) renders as an image box,

2162 -- not a poem. Inert until inject_pseudo_poems tags/append image entries.

2163 if poem.is_image then

2164 return image_render.format_image_entry(poem)

2165 end

2167 local formatted = ""

2169 -- Get semantic color for this poem (key by poem_index, NOT poem.id)

2170 local poem_color_data = poem_colors[poem.poem_index]

2171 local semantic_color = poem_color_data and poem_color_data.color or "gray"

2172 local hex_color = COLOR_CONFIG[semantic_color] or COLOR_CONFIG["gray"]

2174 -- Calculate chronological progress (using poem_index for lookup)

2175 local progress_info = calculate_chronological_progress(poem.poem_index, total_poems)

2177 -- Check if this is a golden poem (exactly 1024 characters)

2178 local is_golden = is_golden_poem(poem)

2180 -- Issue 8-057: Check if this is a boost (reshared content from another author)

2181 local is_boost = is_boost_poem(poem)

2183 -- Build navigation links for this poem (using category prefix for anchors, poem_index for paginated files)

2184 local unique_id = get_unique_poem_filename_id(poem) -- For anchor IDs only (e.g. "messages-0001")

2185 local anchor_id = get_poem_anchor_id(poem)

2186 local poem_index = poem.poem_index or 0 -- Numeric ID for paginated files (e.g. 1 → "0001")

2188 -- Issue 8-012 Phase E: Link to paginated format (similar/0001-01.html)

2189 -- Issue 9-003: Use absolute file:// paths - helper script converts to production URLs

2190 local base_path = ".."

2191 local similar_link = string.format("<a href='%s/similar/%04d-01.html'>similar</a>", base_path, poem_index)

2192 local different_link = string.format("<a href='%s/different/%04d-01.html'>different</a>", base_path, poem_index)

2193 -- Issue 8-039: Chronological now in subdirectory

2194 -- Issue 10-036: the link must name the chronological page that actually holds

2195 -- this poem, and TWO facts decide that filename -- both have to reach here:

2196 -- chrono_mapping poem_index -> {page_number, total_pages, ...}

2197 -- chrono_paginated whether the view was split into numbered pages at all

2198 -- Paginated builds write chronological/NN.html; unpaginated builds write only

2199 -- chronological/index.html. That branch is the one in

2200 -- generate_chronological_index_with_navigation, and this link has to agree

2201 -- with it or it names a file that was never written.

2202 --

2203 -- The old code guessed "01" whenever the mapping was absent. That guess is

2204 -- how a full build shipped 694,530 links all pointing at chronological page

2205 -- 1: this sequential path ran with chrono_mapping = nil, so every poem on

2206 -- every similar/different page claimed to live among the first 88 poems.

2207 -- A guess that is silently wrong for 99% of a corpus is worse than a stop,

2208 -- so the fallback now goes to index.html -- the one file guaranteed to exist

2209 -- in BOTH modes -- and says out loud that it gave up the anchor.

2210 local chrono_info = chrono_mapping and chrono_mapping[poem_index]

2211 local chronological_link

2212 if chrono_info and chrono_paginated and (chrono_info.total_pages or 1) > 1 then

2213 chronological_link = string.format("<a href='%s/chronological/%02d.html#%s'>chronological</a>",

2214 base_path, chrono_info.page_number, anchor_id)

2215 else

2216 -- Unpaginated with a real mapping is the correct, quiet case: index.html

2217 -- IS the whole chronological view, and the anchor resolves inside it.

2218 if not chrono_mapping then

2219 warn_chrono_fallback_once("no chronological mapping reached this generator")

2220 elseif not chrono_info then

2221 warn_chrono_fallback_once(string.format(

2222 "poem_index %d is absent from the chronological mapping", poem_index))

2223 end

2224 chronological_link = string.format("<a href='%s/chronological/index.html#%s'>chronological</a>",

2225 base_path, anchor_id)

2226 end

2228 -- Add file header (notes show original filename, others show numeric ID)

2229 formatted = formatted .. string.format(" -> file: %s\n", get_poem_display_filename(poem))

2230 -- Issue 9-013: text+image posts get a direct "image.png" link below the

2231 -- header. (Image entries never reach here -- they return early above.)

2232 local img_link = image_render.text_image_link(poem)

2233 if img_link ~= "" then formatted = formatted .. " " .. img_link .. "\n" end

2235 -- Issue 8-057: Boost formatting - uses complete nested frame with arrows and [BOOST] label

2236 -- Boost formatting replaces all standard elements (top bar, content, nav, bottom bar)

2237 if is_boost then

2238 -- Escape HTML and apply markdown to content

2239 local text = escape_html(poem.content or "")

2241 -- Issue 10-037: Defensive fallback for blank boost content

2242 -- If content is empty, display the original URI or diagnostic message

2243 if text == "" or text:match("^%s*$") then

2244 local original_uri = poem.metadata and poem.metadata.original_uri

2245 if original_uri then

2246 text = "External post: " .. escape_html(original_uri)

2247 else

2248 text = "(Boost content unavailable)"

2249 end

2250 end

2252 -- Issue 10-039: Make external boost URLs clickable

2253 -- Pattern: "External post: https://..." -> wrap URL in anchor tag

2254 local external_pattern = "^External post: (https?://[^%s]+)$"

2255 local external_url = text:match(external_pattern)

2256 if external_url then

2257 -- Wrap the URL across box lines (boost content width) instead of

2258 -- letting it overflow the box; each line links to the full URL.

2259 text = text_formatter.wrap_external_url("External post: ", external_url, boost_bars.CONTENT_WIDTH)

2260 else

2261 -- Issue 10-041: Wrap long embedded content to fit the boost box.

2262 -- Only wrap non-external-post content (external posts keep URLs intact)

2263 local BOOST_CONTENT_WIDTH = boost_bars.CONTENT_WIDTH

2264 local wrapped_lines = {}

2265 for line in (text .. "\n"):gmatch("(.-)\n") do

2266 local wrapped = text_formatter.wrap_preserving_indent(line, BOOST_CONTENT_WIDTH)

2267 for _, wrapped_line in ipairs(wrapped) do

2268 table.insert(wrapped_lines, wrapped_line)

2269 end

2270 end

2271 text = table.concat(wrapped_lines, "\n")

2272 end

2274 text = apply_markdown_formatting(text)

2276 -- Calculate progress as decimal (0-1) for boost functions

2277 local progress_percent = progress_info.percentage / 100

2279 -- Apply complete boost formatting (includes all frame elements)

2280 local boost_formatted = apply_boost_poem_formatting(

2281 text, progress_percent, similar_link, different_link, chronological_link

2282 )

2283 formatted = formatted .. boost_formatted .. "\n"

2285 -- Render attached images after boost frame

2286 if poem.attachments then

2287 formatted = formatted .. render_attachment_images(poem.attachments)

2288 end

2290 return {

2291 content = formatted,

2292 semantic_color = semantic_color,

2293 progress_percentage = progress_info.percentage,

2294 poem_id = poem.id

2295 }

2296 end

2298 -- Standard formatting for golden and regular poems

2299 -- Generate top progress bar separator (with golden corners if applicable)

2300 local top_dashes = generate_progress_dashes(progress_info, semantic_color, is_golden, "top")

2301 formatted = formatted .. string.format('<span %s>%s</span>',

2302 top_dashes.accessibility,

2303 top_dashes.visual)

2305 -- Add newline after top border for all poems

2306 -- Golden poems: ┐ corner needs newline before ║ content wall on next line

2307 -- Regular poems: progress bar needs newline before content

2308 formatted = formatted .. "\n"

2310 -- Format poem content with content warning handling and whitespace preservation

2311 -- Pass nav links and hex_color for golden poems

2312 local content_formatted = format_content_with_warnings(

2313 poem.content or "", poem.category, poem,

2314 is_golden and similar_link or nil,

2315 is_golden and different_link or nil,

2316 is_golden and chronological_link or nil,

2317 is_golden and hex_color or nil

2318 )

2319 formatted = formatted .. content_formatted

2321 -- Render attached images if present (from ActivityPub extraction)

2322 -- Images appear after poem content, before navigation links

2323 -- Issue 9-010: Images stay with their original post only (no associated_images rendering)

2324 if poem.attachments then

2325 formatted = formatted .. render_attachment_images(poem.attachments)

2326 end

2328 -- For golden poems, content already includes nav in corner boxes

2329 -- For regular poems, add corner-boxed navigation links (top and nav lines only, bottom connects to progress bar)

2330 if not is_golden then

2331 -- Issue 8-035: Calculate progress_chars and hex_color for nav box colorization

2332 local total_chars = LAYOUT.REGULAR_POEM_WIDTH

2333 local progress_chars = math.floor((progress_info.percentage / 100) * total_chars)

2334 local hex_color = COLOR_CONFIG[semantic_color]

2336 formatted = formatted .. "\n"

2337 formatted = formatted .. generate_regular_corner_box_top(progress_chars, hex_color) .. "\n"

2338 formatted = formatted .. generate_regular_corner_box_nav_line(similar_link, different_link, chronological_link, progress_chars, hex_color) .. "\n"

2339 -- No bottom line - corner boxes connect directly to progress bar via junctions

2340 else

2341 -- Golden poems: add newline after nav line (content_formatted doesn't end with newline)

2342 formatted = formatted .. "\n"

2343 end

2345 -- Generate bottom progress bar separator (with junctions for both golden and regular poems)

2346 -- The has_corner_boxes parameter enables junction characters at wall positions

2347 local bottom_dashes = generate_progress_dashes(progress_info, semantic_color, is_golden, "bottom", true)

2348 formatted = formatted .. string.format('<span %s>%s</span>\n',

2349 bottom_dashes.accessibility,

2350 bottom_dashes.visual)

2352 return {

2353 content = formatted,

2354 semantic_color = semantic_color,

2355 progress_percentage = progress_info.percentage,

2356 poem_id = poem.id

2357 }

2362local function format_single_poem_with_warnings(poem)

2363 local formatted = ""

2365 -- Add file header (notes show original filename, others show numeric ID)

2366 formatted = formatted .. string.format(" -> file: %s\n", get_poem_display_filename(poem))

2367 formatted = formatted .. string.rep("-", 80) .. "\n"

2369 -- Format poem content with content warning handling and whitespace preservation

2370 formatted = formatted .. format_content_with_warnings(poem.content or "", poem.category, poem)

2372 -- Render attached images if present

2373 if poem.attachments then

2374 formatted = formatted .. render_attachment_images(poem.attachments)

2375 end

2377 return formatted

2382local function format_single_poem_80_width(poem)

2383 -- Format a single poem for TXT export (80-character width, no HTML)

2384 -- Uses strip_html_tags() to remove HTML and render_attachment_images_txt() for images

2385 local formatted = ""

2387 -- Add file header (notes show original filename, others show numeric ID)

2388 formatted = formatted .. string.format(" -> file: %s\n", get_poem_display_filename(poem))

2389 formatted = formatted .. string.rep("-", 80) .. "\n"

2391 -- Strip HTML tags and format poem content to 80-character width

2392 local clean_content = strip_html_tags(poem.content or "")

2393 formatted = formatted .. wrap_text_80_chars(clean_content)

2395 -- Render attached images as [Image: alt-text] placeholders (not HTML)

2396 if poem.attachments then

2397 formatted = formatted .. render_attachment_images_txt(poem.attachments)

2398 end

2400 return formatted

2406local function format_all_poems_with_progress_and_color(starting_poem, sorted_poems, total_poems, poem_colors, chrono_mapping, chrono_paginated)

2407 local content = ""

2409 -- Add starting poem first with progress visualization

2410 local formatted_starting = format_single_poem_with_progress_and_color(starting_poem, total_poems, poem_colors, chrono_mapping, chrono_paginated)

2411 content = content .. formatted_starting.content .. "\n\n"

2413 -- Add all other poems sorted by similarity/diversity

2414 for _, poem_info in ipairs(sorted_poems) do

2415 if poem_info.id ~= starting_poem.id then -- Skip starting poem since we already added it

2416 local formatted_poem = format_single_poem_with_progress_and_color(poem_info.poem, total_poems, poem_colors, chrono_mapping, chrono_paginated)

2417 content = content .. formatted_poem.content .. "\n\n"

2418 end

2419 end

2421 return content

2426local function format_all_poems_with_content_warnings(starting_poem, sorted_poems)

2427 local content = ""

2428

2429 -- Add starting poem first

2430 content = content .. format_single_poem_with_warnings(starting_poem)

2431 content = content .. "\n\n"

2432

2433 -- Add all other poems sorted by similarity/diversity

2434 for _, poem_info in ipairs(sorted_poems) do

2435 if poem_info.id ~= starting_poem.id then -- Skip starting poem since we already added it

2436 content = content .. format_single_poem_with_warnings(poem_info.poem)

2437 content = content .. "\n\n"

2438 end

2439 end

2440

2441 return content

2446local function format_all_poems_80_width(starting_poem, sorted_poems)

2447 local content = ""

2448

2449 -- Add starting poem first

2450 content = content .. format_single_poem_80_width(starting_poem)

2451 content = content .. "\n\n"

2452

2453 -- Add all other poems sorted by similarity/diversity

2454 for _, poem_info in ipairs(sorted_poems) do

2455 if poem_info.id ~= starting_poem.id then -- Skip starting poem since we already added it

2456 content = content .. format_single_poem_80_width(poem_info.poem)

2457 content = content .. "\n\n"

2458 end

2459 end

2460

2461 return content