scripts/generate-html-parallel

#!/usr/bin/env luajit

-- Multi-threaded HTML page generation using effil
-- Generates similarity and difference pages in parallel for better performance

-- {{{ Early help check (before any requires)
-- Check for --help early, before setting up package paths
for i = 1, #arg do
if arg[i] == "--help" or arg[i] == "-h" then
print([[
Usage: generate-html-parallel [DIR] [OPTIONS]

Options:
--test Generate only first 10 poems (for quick testing)
--similar-only Generate only similarity pages
--different-only Generate only difference pages
--incremental Skip poems that already have HTML files
--threads=N Number of parallel threads (default: 8)

Pagination Options:
--pages=N Number of pages worth of poems to include (default: from config)
--poems-per-page=N Poems per page (default: from config, 100)
Total poems shown = pages × poems-per-page

-h, --help Show this help message

Examples:
generate-html-parallel # Default: 8 threads, all poems
generate-html-parallel . --threads=4 # 4 threads
generate-html-parallel . --incremental # Skip existing files
generate-html-parallel . --similar-only # Only similarity pages
generate-html-parallel . --pages=1 # Show only top 100 poems per file
generate-html-parallel . --pages=5 --poems-per-page=50 # Top 250 poems
]])
os.exit(0)
end
end
-- }}}

-- {{{ local function setup_dir_path
local function setup_dir_path(provided_dir)
if provided_dir then
return provided_dir
end
return "/mnt/mtwo/programming/ai-stuff/neocities-modernization"
end
-- }}}

-- {{{ Parse directory from arguments (before package.path setup)
local function find_dir_arg(args)
for i = 1, #args do
local a = args[i]
-- Skip flags
if a:sub(1, 1) ~= "-" and a:match("^%d+$") == nil then
return a
end
end
return nil
end

local DIR = setup_dir_path(find_dir_arg(arg))
-- }}}

-- Add effil library path
package.cpath = "/home/ritz/programming/ai-stuff/libs/lua/effil-jit/build/?.so;" .. package.cpath
package.path = DIR .. "/libs/?.lua;" .. DIR .. "/src/?.lua;" .. package.path

local effil = require("effil")
local utils = require("utils")
local dkjson = require("dkjson")

-- {{{ local function relative_path
-- Issue 7-003: Show project name instead of "./" when path equals DIR
local function relative_path(absolute_path)
if absolute_path == DIR or absolute_path == DIR .. "/" then
local dir_name = DIR:match("([^/]+)/?$")
return dir_name .. "/"
end
if absolute_path:sub(1, #DIR) == DIR then
local rel = absolute_path:sub(#DIR + 1)
if rel:sub(1, 1) == "/" then rel = rel:sub(2) end
return "./" .. rel
end
return absolute_path
end
-- }}}

-- {{{ Argument parsing
-- Parse command line arguments for more flexible option handling
local function parse_args(args)
local opts = {
dir = nil,
threads = 8,
test = false,
similar_only = false,
different_only = false,
incremental = false, -- Skip existing files
help = false,
-- Issue 8-022: Pagination CLI flags (nil means use config defaults)
pages = nil, -- Number of pages worth of poems to show
poems_per_page = nil -- Poems per page
}

local i = 1
while args and i <= #args do
local a = args[i]
if a == "--test" then
opts.test = true
elseif a == "--similar-only" then
opts.similar_only = true
elseif a == "--different-only" then
opts.different_only = true
elseif a == "--incremental" or a == "-i" then
opts.incremental = true
elseif a == "--help" or a == "-h" then
opts.help = true
elseif a:match("^--threads=") then
opts.threads = tonumber(a:match("^--threads=(%d+)")) or 8
-- Issue 8-022: Parse pagination flags
elseif a:match("^--pages=") then
local val = tonumber(a:match("^--pages=(%d+)"))
if val and val > 0 then
opts.pages = val
else
print("Error: --pages requires a positive integer")
os.exit(1)
end
elseif a:match("^--poems%-per%-page=") then
local val = tonumber(a:match("^--poems%-per%-page=(%d+)"))
if val and val > 0 then
opts.poems_per_page = val
else
print("Error: --poems-per-page requires a positive integer")
os.exit(1)
end
elseif a:match("^%d+$") then
opts.threads = tonumber(a)
elseif a:sub(1, 1) ~= "-" then
opts.dir = a
end
i = i + 1
end

return opts
end

local OPTS = parse_args(arg)
-- Note: --help is handled early (before requires) at top of script
-- }}}

-- Configuration (from parsed arguments)
local NUM_THREADS = OPTS.threads
local TEST_MODE = OPTS.test
local SIMILARITY_ONLY = OPTS.similar_only
local DIFFERENCE_ONLY = OPTS.different_only
local INCREMENTAL_MODE = OPTS.incremental
local MAX_TEST_PAGES = 10
local USE_CACHE = true -- Use pre-computed diversity sequences if available

-- Update DIR if provided in args
if OPTS.dir then
DIR = OPTS.dir
end

-- {{{ Issue 8-022: Load pagination config and apply CLI overrides
-- Issue 10-014: Migrated from input-sources.json to unified config.lua
local function load_pagination_config()
-- Default values (fallback if config missing)
local pagination = {
poems_per_page = 100,
max_pages_per_poem = 15 -- 0 means all poems (no limit)
}

-- Load from config.lua
local config_file = DIR .. "/config.lua"
local ok, config = pcall(dofile, config_file)
if ok and config and config.pagination then
pagination.poems_per_page = config.pagination.poems_per_page or pagination.poems_per_page
pagination.max_pages_per_poem = config.pagination.max_pages_per_poem or pagination.max_pages_per_poem
end

-- CLI overrides (Issue 8-022)
if OPTS.poems_per_page then
pagination.poems_per_page = OPTS.poems_per_page
end
if OPTS.pages then
pagination.max_pages_per_poem = OPTS.pages
end

return pagination
end

local PAGINATION = load_pagination_config()

-- Calculate max poems to include in each generated file
-- 0 means no limit (show all poems)
local MAX_POEMS_TO_SHOW = PAGINATION.max_pages_per_poem * PAGINATION.poems_per_page
local DIVERSITY_LIMIT = MAX_POEMS_TO_SHOW -- Limit diversity sequence to same amount
-- }}}

-- Color configuration (shared)
local COLOR_CONFIG = {
red = "#dc3c3c",
blue = "#3c78dc",
green = "#3cb45a",
purple = "#8c3cc8",
orange = "#e68c3c",
yellow = "#c8b428",
gray = "#787878"
}

-- Issue 8-057: Boost visual formatting color scheme for worker threads
-- Boosts are reshared content from other fediverse users, displayed with nested frames
local BOOST_COLOR_CONFIG = {
arrow = "#dc3c3c", -- Red: ◀─ and ─▶ arrows, [BOOST] label
outer_frame = "#3c78dc", -- Blue: ╔═╗║╚═╝ outer frame
inner_box = "#2aa198", -- Teal: ┌─┐│└─┘ inner content box
content_text = "#c8b428" -- Yellow: boosted text content
}

-- {{{ Worker function for similarity page generation
-- Note: This function must not capture any upvalues - all data passed as parameters
-- Issue 8-022: Added max_poems_to_show parameter to limit output size
-- Issue 8-057: Added boost visual formatting support (is_boost flag in poem array)
local function similarity_worker(poem_id, poem_content, poem_category, poem_is_boost,
similarities_for_poem, all_poems_array, poem_colors_table,
max_poem_id, output_dir, max_poems_to_show, boost_colors)
-- CRITICAL FIX: Copy effil.tables to local Lua tables at worker start
-- This avoids catastrophic IPC overhead (17B accesses → single O(n) copy)
-- See issue 8-002 "Bug 2: Catastrophic effil.table Access Overhead"

local local_poems_array = {}
for i = 1, #all_poems_array do
local_poems_array[i] = all_poems_array[i]
end

local local_similarities = {}
for k, v in pairs(similarities_for_poem) do
local_similarities[k] = v
end

local local_colors = {}
for k, v in pairs(poem_colors_table) do
local_colors[k] = v
end

local local_boost_colors = {}
for k, v in pairs(boost_colors) do
local_boost_colors[k] = v
end

-- {{{ Issue 8-057: Boost formatting helper functions (no upvalues)
-- Simplified version for similarity/different pages (no navigation section)

-- Generate boost top border with arrow and [BOOST] label
local function boost_top_border(progress_percent, colors)
local BAR_WIDTH = 78
local LABEL = "[BOOST]"
local LABEL_LEN = 7

local progress_chars = math.floor(progress_percent * BAR_WIDTH)
if progress_chars < LABEL_LEN + 2 then
progress_chars = LABEL_LEN + 2
end

local label_center = math.floor(progress_chars / 2)
local label_start = label_center - math.floor(LABEL_LEN / 2)
if label_start < 1 then label_start = 1 end

local colored_arrow = string.format('◀─', colors.arrow)
local colored_frame_left = string.format('╔', colors.outer_frame)
local colored_frame_right = string.format('╗', colors.outer_frame)

local colored_bar = ""
for i = 1, BAR_WIDTH do
if i >= label_start and i < label_start + LABEL_LEN then
local char = LABEL:sub(i - label_start + 1, i - label_start + 1)
colored_bar = colored_bar .. string.format('%s', colors.arrow, char)
elseif i <= progress_chars then
colored_bar = colored_bar .. string.format('═', colors.outer_frame)
else
colored_bar = colored_bar .. string.format('─', colors.outer_frame)
end
end

return colored_arrow .. colored_frame_left .. colored_bar .. colored_frame_right
end

-- Generate inner box top border
local function boost_inner_top(colors)
local outer_wall = string.format('║', colors.outer_frame)
local inner_corner_left = string.format('┌', colors.inner_box)
local inner_corner_right = string.format('┐', colors.inner_box)
local inner_dash = string.format('─', colors.inner_box)
return outer_wall .. " " .. inner_corner_left .. string.rep(inner_dash, 76) .. inner_corner_right .. " " .. outer_wall
end

-- Generate inner box bottom border
local function boost_inner_bottom(colors)
local outer_wall = string.format('║', colors.outer_frame)
local inner_corner_left = string.format('└', colors.inner_box)
local inner_corner_right = string.format('┘', colors.inner_box)
local inner_dash = string.format('─', colors.inner_box)
return outer_wall .. " " .. inner_corner_left .. string.rep(inner_dash, 76) .. inner_corner_right .. " " .. outer_wall
end

-- Generate content line with nested frames
local function boost_content_line(line, colors)
local CONTENT_WIDTH = 74
local visible_length = #line -- Simplified: byte length (HTML tags will extend this)
local padded_line
if visible_length >= CONTENT_WIDTH then
padded_line = line
else
padded_line = line .. string.rep(" ", CONTENT_WIDTH - visible_length)
end

local outer_wall = string.format('║', colors.outer_frame)
local inner_wall = string.format('│', colors.inner_box)
local colored_content = string.format('%s', colors.content_text, padded_line)

return outer_wall .. " " .. inner_wall .. " " .. colored_content .. " " .. inner_wall .. " " .. outer_wall
end

-- Generate bottom border with arrow
local function boost_bottom_border(progress_percent, colors)
local BAR_WIDTH = 78
local progress_chars = math.floor(progress_percent * BAR_WIDTH)

local outer_corner_left = string.format('╚', colors.outer_frame)
local outer_corner_right = string.format('╝', colors.outer_frame)
local colored_arrow = string.format('─▶', colors.arrow)

local bar_str = ""
for i = 1, BAR_WIDTH do
local in_progress = i <= progress_chars
if in_progress then
bar_str = bar_str .. string.format('═', colors.outer_frame)
else
bar_str = bar_str .. string.format('─', colors.outer_frame)
end
end

return outer_corner_left .. bar_str .. outer_corner_right .. colored_arrow
end

-- Apply complete boost formatting (simplified - no nav section)
local function apply_boost_formatting(content, progress_percent, colors)
local lines = {}
table.insert(lines, boost_top_border(progress_percent, colors))
table.insert(lines, boost_inner_top(colors))

for line in (content .. "\n"):gmatch("(.-)\n") do
table.insert(lines, boost_content_line(line, colors))
end

table.insert(lines, boost_inner_bottom(colors))
table.insert(lines, boost_bottom_border(progress_percent, colors))

return table.concat(lines, "\n")
end
-- }}} End boost formatting helpers

-- Generate similarity ranking
local ranked_poems = {}

-- Add starting poem first
table.insert(ranked_poems, {
id = poem_id,
content = poem_content,
category = poem_category,
is_boost = poem_is_boost,
similarity = 1.0
})

-- Add other poems sorted by similarity (using local copies of effil.tables)
-- Issue 8-057: Poem array now has 4 elements per poem: id, content, category, is_boost
local other_poems = {}
for i = 1, #local_poems_array, 4 do
local other_id = local_poems_array[i]
local other_content = local_poems_array[i + 1]
local other_category = local_poems_array[i + 2]
local other_is_boost = local_poems_array[i + 3]

if other_id ~= poem_id then
local sim_score = local_similarities[tostring(other_id)] or 0
table.insert(other_poems, {
id = other_id,
content = other_content,
category = other_category,
is_boost = other_is_boost,
similarity = sim_score
})
end
end

table.sort(other_poems, function(a, b)
return a.similarity > b.similarity
end)

-- Issue 8-022: Limit poems to max_poems_to_show (includes starting poem)
local poems_limit = max_poems_to_show > 0 and (max_poems_to_show - 1) or #other_poems
for i, p in ipairs(other_poems) do
if i > poems_limit then break end
table.insert(ranked_poems, p)
end

-- Generate HTML content
local content_parts = {}
for _, poem_info in ipairs(ranked_poems) do
local pid = poem_info.id

-- Calculate progress (as decimal 0-1 for boost functions)
local progress_decimal = pid / max_poem_id
local progress_pct = progress_decimal * 100
local progress_chars = math.floor((progress_pct / 100) * 80)
local remaining_chars = 80 - progress_chars

-- Get color (using local copy of effil.table)
local color_name = local_colors[tostring(pid)] or "gray"
local hex_color = ({
red = "#dc3c3c", blue = "#3c78dc", green = "#3cb45a",
purple = "#8c3cc8", orange = "#e68c3c", yellow = "#c8b428", gray = "#787878"
})[color_name] or "#787878"

-- Format poem entry
table.insert(content_parts, string.format(" -> file: %s/%s.txt\n", poem_info.category or "unknown", pid))

-- Issue 8-057: Apply boost formatting for boosted content
if poem_info.is_boost then
-- Boost poems get nested frame with arrows and [BOOST] label
local formatted_content = apply_boost_formatting(poem_info.content or "", progress_decimal, local_boost_colors)
table.insert(content_parts, formatted_content .. "\n\n")
else
-- Regular poems get standard progress bar formatting
local progress_section = string.rep("═", progress_chars)
local remaining_section = string.rep("─", remaining_chars)
local progress_bar = string.format('%s%s',
hex_color, progress_section, remaining_section)

table.insert(content_parts, string.format('<div aria-label="eighty dashes. %s.">%s</div>\n', color_name, progress_bar))
table.insert(content_parts, (poem_info.content or "") .. "\n")
table.insert(content_parts, string.format('<div aria-label="eighty dashes. %s.">%s</div>\n\n', color_name, progress_bar))
end
end

local html_content = table.concat(content_parts)

-- Generate unique filename ID (category prefix for cross-category uniqueness)
local unique_id = string.format("%s-%04d", poem_category, poem_id)

-- Generate HTML
local html = string.format([[<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Poems sorted by similarity to: %s #%d</title>
</head>
<body>
<center>
<h1>Poetry Collection</h1>
All poems sorted by similarity to: %s #%d
<pre>
%s
</pre>
</center>
</body>
</html>]], poem_category, poem_id, poem_category, poem_id, html_content)

-- Write file (using category prefix for unique filename - Issue 8-019)
local filename = string.format("%s/similar/%s.html", output_dir, unique_id)
local f = io.open(filename, "w")
if f then
f:write(html)
f:close()
return true
end
return false
end
-- }}}

-- {{{ Worker function for difference page generation (centroid-based diversity)
-- Note: This function must not capture any upvalues - all data passed as parameters
-- Issue 8-057: Added boost visual formatting support
local function diversity_worker(poem_id, poem_content, poem_category, poem_is_boost,
starting_embedding_flat, all_poems_array, all_embeddings_flat,
embedding_dim, poem_colors_table, max_poem_id, output_dir,
diversity_limit, boost_colors)
-- CRITICAL FIX: Copy effil.tables to local Lua tables at worker start
-- This is especially important for diversity_worker which has O(n²) access patterns
-- Without this fix: ~17 BILLION IPC calls per sequence (~5 hours)
-- With this fix: single O(n) copy, then fast local access
-- See issue 8-002 "Bug 2: Catastrophic effil.table Access Overhead"

local local_poems_array = {}
for i = 1, #all_poems_array do
local_poems_array[i] = all_poems_array[i]
end

local local_embeddings_flat = {}
for i = 1, #all_embeddings_flat do
local_embeddings_flat[i] = all_embeddings_flat[i]
end

local local_starting_embedding = {}
for i = 1, #starting_embedding_flat do
local_starting_embedding[i] = starting_embedding_flat[i]
end

local local_colors = {}
for k, v in pairs(poem_colors_table) do
local_colors[k] = v
end

local local_boost_colors = {}
for k, v in pairs(boost_colors) do
local_boost_colors[k] = v
end

-- {{{ Issue 8-057: Boost formatting helper functions (no upvalues)
-- Simplified version for similarity/different pages (no navigation section)

local function boost_top_border(progress_percent, colors)
local BAR_WIDTH = 78
local LABEL = "[BOOST]"
local LABEL_LEN = 7

local progress_chars = math.floor(progress_percent * BAR_WIDTH)
if progress_chars < LABEL_LEN + 2 then
progress_chars = LABEL_LEN + 2
end

local label_center = math.floor(progress_chars / 2)
local label_start = label_center - math.floor(LABEL_LEN / 2)
if label_start < 1 then label_start = 1 end

return colored_arrow .. colored_frame_left .. colored_bar .. colored_frame_right
end

local function boost_inner_top(colors)
local outer_wall = string.format('║', colors.outer_frame)
local inner_corner_left = string.format('┌', colors.inner_box)
local inner_corner_right = string.format('┐', colors.inner_box)
local inner_dash = string.format('─', colors.inner_box)
return outer_wall .. " " .. inner_corner_left .. string.rep(inner_dash, 76) .. inner_corner_right .. " " .. outer_wall
end

local function boost_inner_bottom(colors)
local outer_wall = string.format('║', colors.outer_frame)
local inner_corner_left = string.format('└', colors.inner_box)
local inner_corner_right = string.format('┘', colors.inner_box)
local inner_dash = string.format('─', colors.inner_box)
return outer_wall .. " " .. inner_corner_left .. string.rep(inner_dash, 76) .. inner_corner_right .. " " .. outer_wall
end

local function boost_content_line(line, colors)
local CONTENT_WIDTH = 74
local visible_length = #line
local padded_line
if visible_length >= CONTENT_WIDTH then
padded_line = line
else
padded_line = line .. string.rep(" ", CONTENT_WIDTH - visible_length)
end

return outer_wall .. " " .. inner_wall .. " " .. colored_content .. " " .. inner_wall .. " " .. outer_wall
end

local function boost_bottom_border(progress_percent, colors)
local BAR_WIDTH = 78
local progress_chars = math.floor(progress_percent * BAR_WIDTH)

return outer_corner_left .. bar_str .. outer_corner_right .. colored_arrow
end

local function apply_boost_formatting(content, progress_percent, colors)
local lines = {}
table.insert(lines, boost_top_border(progress_percent, colors))
table.insert(lines, boost_inner_top(colors))

for line in (content .. "\n"):gmatch("(.-)\n") do
table.insert(lines, boost_content_line(line, colors))
end

table.insert(lines, boost_inner_bottom(colors))
table.insert(lines, boost_bottom_border(progress_percent, colors))

return table.concat(lines, "\n")
end
-- }}} End boost formatting helpers

-- Helper: cosine distance between two embeddings (passed as flat arrays with offset)
local function cosine_distance(emb1, emb2)
local dot_product = 0
local norm1 = 0
local norm2 = 0

for i = 1, #emb1 do
dot_product = dot_product + (emb1[i] * emb2[i])
norm1 = norm1 + (emb1[i] * emb1[i])
norm2 = norm2 + (emb2[i] * emb2[i])
end

norm1 = math.sqrt(norm1)
norm2 = math.sqrt(norm2)

if norm1 == 0 or norm2 == 0 then
return 1.0
end

return 1.0 - (dot_product / (norm1 * norm2))
end

-- Helper: calculate centroid of a list of embeddings
local function calculate_centroid(embeddings_list)
if #embeddings_list == 0 then return nil end

local dim = #embeddings_list[1]
local centroid = {}
for i = 1, dim do centroid[i] = 0 end

for _, emb in ipairs(embeddings_list) do
for i = 1, dim do
centroid[i] = centroid[i] + emb[i]
end
end

for i = 1, dim do
centroid[i] = centroid[i] / #embeddings_list
end

return centroid
end

-- Build starting embedding as table (using local copy)
local starting_embedding = {}
for i = 1, embedding_dim do
starting_embedding[i] = local_starting_embedding[i]
end

-- Build list of other poems with embeddings (using local copies)
-- Issue 8-057: Poem array now has 4 elements per poem: id, content, category, is_boost
local remaining_poems = {}
local num_poems = #local_poems_array / 4

for i = 1, num_poems do
local idx = (i - 1) * 4 + 1
local other_id = local_poems_array[idx]
local other_content = local_poems_array[idx + 1]
local other_category = local_poems_array[idx + 2]
local other_is_boost = local_poems_array[idx + 3]

if other_id ~= poem_id then
-- Extract embedding for this poem (using local copy)
local emb_start = (i - 1) * embedding_dim + 1
local embedding = {}
for j = 1, embedding_dim do
embedding[j] = local_embeddings_flat[emb_start + j - 1]
end

table.insert(remaining_poems, {
id = other_id,
content = other_content,
category = other_category,
is_boost = other_is_boost,
embedding = embedding
})
end
end

-- Generate diversity sequence using centroid-based selection
local diversity_sequence = {{
id = poem_id,
content = poem_content,
category = poem_category,
is_boost = poem_is_boost
}}
local selected_embeddings = {starting_embedding}

-- Limit diversity sequence if specified
local max_sequence = diversity_limit > 0 and diversity_limit or (#remaining_poems + 1)

while #remaining_poems > 0 and #diversity_sequence < max_sequence do
local centroid = calculate_centroid(selected_embeddings)
if not centroid then break end

-- Find poem with maximum distance from centroid
local max_dist = -1
local max_idx = -1

for i, poem_info in ipairs(remaining_poems) do
local dist = cosine_distance(centroid, poem_info.embedding)
if dist > max_dist then
max_dist = dist
max_idx = i
end
end

if max_idx > 0 then
local selected = remaining_poems[max_idx]
table.insert(diversity_sequence, {
id = selected.id,
content = selected.content,
category = selected.category,
is_boost = selected.is_boost
})
table.insert(selected_embeddings, selected.embedding)
table.remove(remaining_poems, max_idx)
else
break
end
end

-- Generate HTML content
local content_parts = {}
for _, poem_info in ipairs(diversity_sequence) do
local pid = poem_info.id

-- Format poem entry
table.insert(content_parts, string.format(" -> file: %s/%s.txt\n", poem_info.category or "unknown", pid))

-- Issue 8-057: Apply boost formatting for boosted content
if poem_info.is_boost then
local formatted_content = apply_boost_formatting(poem_info.content or "", progress_decimal, local_boost_colors)
table.insert(content_parts, formatted_content .. "\n\n")
else
-- Generate progress bar
local progress_section = string.rep("═", progress_chars)
local remaining_section = string.rep("─", remaining_chars)
local progress_bar = string.format('%s%s',
hex_color, progress_section, remaining_section)

-- Format poem entry
table.insert(content_parts, string.format('<div aria-label="eighty dashes. %s.">%s</div>\n', color_name, progress_bar))
table.insert(content_parts, (poem_info.content or "") .. "\n")
table.insert(content_parts, string.format('<div aria-label="eighty dashes. %s.">%s</div>\n\n', color_name, progress_bar))
end
end

local html_content = table.concat(content_parts)

-- Generate HTML
-- Generate unique filename ID (category prefix for cross-category uniqueness)
local unique_id = string.format("%s-%04d", poem_category, poem_id)

local html = string.format([[<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Poems sorted by difference from: %s #%d</title>
</head>
<body>
<center>
<h1>Poetry Collection</h1>
All poems sorted by difference from: %s #%d
<pre>
%s
</pre>
</center>
</body>
</html>]], poem_category, poem_id, poem_category, poem_id, html_content)

-- Write file (using category prefix for unique filename - Issue 8-019)
local filename = string.format("%s/different/%s.html", output_dir, unique_id)
local f = io.open(filename, "w")
if f then
f:write(html)
f:close()
return true
end
return false
end
-- }}}

-- {{{ Worker function for cached difference page generation (uses pre-computed sequences)
-- Much faster than on-the-fly computation - just looks up poem data and generates HTML
-- Issue 8-022: Added max_poems_to_show parameter to limit output size
-- Issue 8-057: Added boost visual formatting support
local function cached_diversity_worker(poem_id, diversity_sequence, all_poems_lookup,
poem_colors_table, max_poem_id, output_dir,
max_poems_to_show, boost_colors)
-- CRITICAL FIX: Copy effil.tables to local Lua tables at worker start
-- See issue 8-002 "Bug 2: Catastrophic effil.table Access Overhead"

-- Issue 8-022: Limit sequence length based on pagination settings
local sequence_limit = max_poems_to_show > 0 and max_poems_to_show or #diversity_sequence
local local_sequence = {}
for i = 1, math.min(#diversity_sequence, sequence_limit) do
local_sequence[i] = diversity_sequence[i]
end

local local_poems_lookup = {}
for k, v in pairs(all_poems_lookup) do
local_poems_lookup[k] = v
end

local local_colors = {}
for k, v in pairs(poem_colors_table) do
local_colors[k] = v
end

local local_boost_colors = {}
for k, v in pairs(boost_colors) do
local_boost_colors[k] = v
end

-- {{{ Issue 8-057: Boost formatting helper functions (no upvalues)
local function boost_top_border(progress_percent, colors)
local BAR_WIDTH = 78
local LABEL = "[BOOST]"
local LABEL_LEN = 7