Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
// PNG text metadata helpers for Stable Diffusion-compatible renders.
//
// The image upload path re-encodes images to PNG with sharp, which deliberately
// drops ancillary chunks. Read the bounded text chunks before that conversion so
// prompt provenance survives as structured application metadata instead of being
// lost with the source bytes.
import { open } from 'node:fs/promises';
import { inflateSync } from 'node:zlib';
const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
const MAX_PNG_CHUNKS = 128;
// The local projection and catalog sync validator use the same bounds. Keep
// this below the schema layer so image uploads do not import catalog/Zod code.
export const GENERATION_METADATA_LIMITS = Object.freeze({
format: 64, parameters: 64 * 1024, prompt: 16_000, negativePrompt: 16_000,
steps: 100_000, sampler: 256, cfgScale: 1_000, seed: 128,
width: 100_000, height: 100_000, modelHash: 256, model: 512,
jsonChars: 96 * 1024,
});
const MAX_TEXT_BYTES = GENERATION_METADATA_LIMITS.parameters;
const MAX_TEXT_CHUNK_BYTES = 256 * 1024;
const TEXT_CHUNK_TYPES = new Set(['tEXt', 'zTXt', 'iTXt']);
const METADATA_KEYS = new Set([
'parameters',
'prompt',
'negative_prompt',
'negative prompt',
'negativeprompt',
'sd-metadata',
'sd_metadata',
'invokeai_metadata',
'metadata',
]);
const asBuffer = (value) => {
if (Buffer.isBuffer(value)) return value;
if (value instanceof Uint8Array) return Buffer.from(value);
return null;
};
const boundedText = (value, max = MAX_TEXT_BYTES) => {
if (typeof value !== 'string') return null;
const text = value.slice(0, max).trim();
return text || null;
};
const firstText = (...values) => values.find((value) => typeof value === 'string' && value.trim())?.trim() || null;
const finiteNumber = (value) => {
if (typeof value !== 'number' && (typeof value !== 'string' || !value.trim())) return null;
const number = typeof value === 'number' ? value : Number(value);
return Number.isFinite(number) ? number : null;
};
const integerOrString = (value) => {
if (typeof value === 'string' && value.trim()) {
const trimmed = value.trim();
const number = Number(trimmed);
return Number.isSafeInteger(number) && String(number) === trimmed
? number : boundedText(trimmed, GENERATION_METADATA_LIMITS.seed);
}
if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
return null;
};
function addIfPresent(target, key, value) {
if (value === null || value === undefined || value === '') return;
target[key] = value;
}
function parseSize(value) {
if (typeof value !== 'string') return {};
const match = /^(\d+)\s*x\s*(\d+)$/i.exec(value.trim());
if (!match) return {};
return { width: Number(match[1]), height: Number(match[2]) };
}
// Per-field character caps alone are insufficient: JSON escaping can multiply
// a string's serialized size. This is a bounded provenance projection (the
// original PNG/sidecar remains the source), so shorten the redundant raw
// parameters first, retaining the structured fields whenever they fit.
function boundMetadataJson(metadata) {
for (const key of ['parameters', 'prompt', 'negativePrompt', 'model', 'sampler', 'modelHash', 'format', 'seed']) {
const jsonChars = JSON.stringify(metadata).length;
if (jsonChars <= GENERATION_METADATA_LIMITS.jsonChars) break;
const value = metadata[key];
if (typeof value !== 'string') continue;
const available = GENERATION_METADATA_LIMITS.jsonChars - (jsonChars - JSON.stringify(value).length);
let low = 0;
let high = value.length;
while (low < high) {
const middle = Math.ceil((low + high) / 2);
if (JSON.stringify(value.slice(0, middle)).length <= available) low = middle;
else high = middle - 1;
}
if (low) metadata[key] = value.slice(0, low);
else delete metadata[key];
}
return metadata;
}
/**
* Normalize the useful generation fields from either PNG metadata or a PortOS
* image sidecar. Unknown sidecar fields are intentionally ignored: catalog
* metadata is a small, stable provenance projection rather than a copy of an
* entire provider-specific sidecar or workflow graph.
*/
export function normalizeGenerationMetadata(input) {
if (!input || typeof input !== 'object' || Array.isArray(input)) return {};
const metadata = {};
addIfPresent(metadata, 'format', boundedText(firstText(input.format), GENERATION_METADATA_LIMITS.format));
addIfPresent(metadata, 'parameters', boundedText(input.parameters));
addIfPresent(metadata, 'prompt', boundedText(firstText(input.prompt, input.positivePrompt, input.positive_prompt), GENERATION_METADATA_LIMITS.prompt));
addIfPresent(metadata, 'negativePrompt', boundedText(firstText(input.negativePrompt, input.negativeprompt, input.negative_prompt, input['negative prompt'], input.negative), GENERATION_METADATA_LIMITS.negativePrompt));
const steps = finiteNumber(input.steps ?? input.num_steps);
if (Number.isInteger(steps) && steps >= 0 && steps <= GENERATION_METADATA_LIMITS.steps) metadata.steps = steps;
addIfPresent(metadata, 'sampler', boundedText(firstText(input.sampler, input.samplerName, input.sampler_name), GENERATION_METADATA_LIMITS.sampler));
const cfgScale = finiteNumber(input.cfgScale ?? input.cfg_scale ?? input.guidanceScale ?? input.guidance_scale ?? input.guidance);
if (cfgScale !== null && cfgScale >= 0 && cfgScale <= GENERATION_METADATA_LIMITS.cfgScale) metadata.cfgScale = cfgScale;
const seed = integerOrString(input.seed);
if (seed !== null) metadata.seed = seed;
const size = parseSize(input.size);
const width = finiteNumber(input.width ?? size.width);
const height = finiteNumber(input.height ?? size.height);
if (Number.isInteger(width) && width > 0 && width <= GENERATION_METADATA_LIMITS.width) metadata.width = width;
if (Number.isInteger(height) && height > 0 && height <= GENERATION_METADATA_LIMITS.height) metadata.height = height;
addIfPresent(metadata, 'modelHash', boundedText(firstText(input.modelHash, input.model_hash), GENERATION_METADATA_LIMITS.modelHash));
addIfPresent(metadata, 'model', boundedText(firstText(input.model, input.modelName, input.model_name, input.modelId, input.model_id), GENERATION_METADATA_LIMITS.model));
return boundMetadataJson(metadata);
}
function readNullByte(buffer, start) {
const index = buffer.indexOf(0, start);
return index >= start ? index : -1;
}
function inflateText(buffer) {
try {
const inflated = inflateSync(buffer, { maxOutputLength: MAX_TEXT_BYTES });
return boundedText(inflated.toString('utf8'));
} catch {
return null;
}
}
function decodeTextChunk(type, data) {
const keywordEnd = readNullByte(data, 0);
if (keywordEnd <= 0 || keywordEnd > 79) return null;
const keyword = data.toString('latin1', 0, keywordEnd);
const lowerKeyword = keyword.toLowerCase();
if (type === 'tEXt') {
return { keyword, text: boundedText(data.subarray(keywordEnd + 1).toString('utf8')) };
}
if (type === 'zTXt') {
if (keywordEnd + 2 > data.length || data[keywordEnd + 1] !== 0) return null;
return { keyword, text: inflateText(data.subarray(keywordEnd + 2)) };
}
// iTXt: keyword, compression flag, compression method, language tag,
// translated keyword, then the UTF-8 text. Only method 0 is defined today.
const header = keywordEnd + 3;
if (header > data.length || (data[keywordEnd + 1] !== 0 && data[keywordEnd + 1] !== 1) || data[keywordEnd + 2] !== 0) return null;
const languageEnd = readNullByte(data, header);
if (languageEnd < 0) return null;
const translatedEnd = readNullByte(data, languageEnd + 1);
if (translatedEnd < 0) return null;
const textData = data.subarray(translatedEnd + 1);
const text = data[keywordEnd + 1] === 1 ? inflateText(textData) : boundedText(textData.toString('utf8'));
return { keyword, lowerKeyword, text };
}
function readTextChunks(value) {
const buffer = asBuffer(value);
if (!buffer || buffer.length < PNG_SIGNATURE.length || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return [];
const chunks = [];
let offset = PNG_SIGNATURE.length;
let count = 0;
while (offset + 12 <= buffer.length && count++ < MAX_PNG_CHUNKS) {
const length = buffer.readUInt32BE(offset);
const chunkEnd = offset + 12 + length;
if (chunkEnd > buffer.length) break;
const type = buffer.toString('ascii', offset + 4, offset + 8);
if (!/^[A-Za-z]{4}$/.test(type)) break;
if (TEXT_CHUNK_TYPES.has(type) && length <= MAX_TEXT_CHUNK_BYTES) {
const decoded = decodeTextChunk(type, buffer.subarray(offset + 8, offset + 8 + length));
if (decoded?.text) chunks.push(decoded);
}
offset = chunkEnd;
if (type === 'IEND') break;
}
return chunks;
}
function parseJsonObject(text) {
if (!text || text.length > MAX_TEXT_BYTES) return null;
try {
const value = JSON.parse(text);
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
function parseSettings(settings) {
const values = {};
let start = 0;
let quoted = false;
let escaped = false;
for (let index = 0; index <= settings.length; index++) {
const char = settings[index];
if (escaped) { escaped = false; continue; }
if (quoted && char === '\\') { escaped = true; continue; }
if (char === '"') quoted = !quoted;
if (index < settings.length && (char !== ',' || quoted)) continue;
const match = /^\s*([^:]+):\s*(.*?)\s*$/.exec(settings.slice(start, index));
start = index + 1;
if (!match) continue;
let value = match[2];
if (value.startsWith('"') && value.endsWith('"')) {
try { value = JSON.parse(value); } catch { /* Keep malformed text as evidence. */ }
}
values[match[1].trim().toLowerCase()] = value;
}
return values;
}
/** Parse the common Automatic1111 `parameters` text block. */
export function parseStableDiffusionParameters(value) {
const parameters = boundedText(value);
if (!parameters) return {};
const lines = parameters.replace(/\r\n?/g, '\n').split('\n');
const settingsLine = lines.findIndex((line) => /^\s*Steps:\s*/i.test(line));
const negativeLine = lines.findIndex((line) => /^\s*Negative prompt:\s*/i.test(line));
const promptEnd = [settingsLine, negativeLine].filter((index) => index >= 0).sort((a, b) => a - b)[0] ?? lines.length;
const parsed = { format: 'a1111', parameters };
addIfPresent(parsed, 'prompt', boundedText(lines.slice(0, promptEnd).join('\n')));
if (negativeLine >= 0 && (settingsLine < 0 || negativeLine < settingsLine)) {
const end = settingsLine >= 0 ? settingsLine : lines.length;
addIfPresent(parsed, 'negativePrompt', boundedText(lines.slice(negativeLine, end).join('\n').replace(/^\s*Negative prompt:\s*/i, '')));
}
const settings = settingsLine >= 0 ? lines.slice(settingsLine).join(' ') : '';
const values = parseSettings(settings);
Object.assign(parsed, {
steps: values.steps,
sampler: values.sampler || values['sampler name'],
cfgScale: values['cfg scale'] || values['guidance scale'],
seed: values.seed,
size: values.size,
modelHash: values['model hash'],
model: values.model,
});
return normalizeGenerationMetadata(parsed);
}
/**
* Extract a bounded, structured provenance projection from PNG text chunks.
* Malformed or unsupported metadata is treated as absent so an image upload
* remains usable; sharp remains the authoritative image-format validator.
*/
export function extractPngGenerationMetadata(value) {
return extractGenerationMetadataEntries(readTextChunks(value));
}
// Container adapters supply bounded text entries; projection and field policy
// stay identical for PNG uploads and video tags.
export function extractGenerationMetadataEntries(entries) {
const result = {};
for (const chunk of entries) {
if (typeof chunk.keyword !== 'string' || typeof chunk.text !== 'string' || chunk.text.length > MAX_TEXT_BYTES) continue;
const key = chunk.keyword.toLowerCase();
let candidate = {};
if (key === 'parameters') {
candidate = parseStableDiffusionParameters(chunk.text);
} else if (METADATA_KEYS.has(key) || key === 'comment' || key === 'description') {
const json = parseJsonObject(chunk.text);
candidate = json ? normalizeGenerationMetadata(json)
: /^(comment|description)$/.test(key) && /(?:^|\n)Steps:\s*\d+/i.test(chunk.text)
? parseStableDiffusionParameters(chunk.text)
: normalizeGenerationMetadata({ [key]: chunk.text });
}
for (const [field, fieldValue] of Object.entries(candidate)) {
if (result[field] === undefined || result[field] === null || result[field] === '') result[field] = fieldValue;
}
}
return normalizeGenerationMetadata(result);
}
// Seek past pixel data rather than reading a potentially huge PNG into memory.
export async function extractPngGenerationMetadataFile(path) {
const file = await open(path, 'r');
try {
const signature = Buffer.alloc(8);
await file.read(signature, 0, 8, 0);
if (!signature.equals(PNG_SIGNATURE)) return {};
const { size } = await file.stat();
const chunks = [signature];
let offset = 8;
for (let count = 0; count < MAX_PNG_CHUNKS && offset + 12 <= size; count++) {
const header = Buffer.alloc(8);
await file.read(header, 0, 8, offset);
const length = header.readUInt32BE(0);
const type = header.toString('ascii', 4, 8);
if (offset + length + 12 > size) break;
if (TEXT_CHUNK_TYPES.has(type) && length <= MAX_TEXT_CHUNK_BYTES) {
const chunk = Buffer.alloc(length + 12);
await file.read(chunk, 0, chunk.length, offset);
chunks.push(chunk);
}
offset += length + 12;
if (type === 'IEND') break;
}
return extractPngGenerationMetadata(Buffer.concat(chunks));
} finally {
await file.close();
}
}