hoi4-agent-tools 2.8.10 → 3.0.0

package/dist/hoi4_agent_tools/gui/assets.js

@@ -110,6 +110,7 @@ export function parseBmFont(text) {
                             ? fields.width
                             : 0,
                     page: typeof fields.page === 'number' ? fields.page : 0,
+                    channelMask: typeof fields.chnl === 'number' ? fields.chnl : 15,
                 });
             }
             recognised = true;
@@ -155,6 +156,7 @@ export class GuiAssetCatalog {
     basenames = new Map();
     rasters = new Map();
     frames = new Map();
+    countryFlags = new Map();
     glyphRasters = new Map();
     metrics = new Map();
     fontDefinitions = new Map();
@@ -292,6 +294,192 @@ export class GuiAssetCatalog {
     loadSecondarySpriteFrame(sprite, requestedFrame) {
         return this.loadSpriteTextureFrame(sprite, sprite.texturePath2, requestedFrame, 'secondary');
     }
+    loadCountryFlag(tag, sprite, ideology, slotName) {
+        const normalizedTag = tag
+            .trim()
+            .replace(/[^A-Za-z0-9_]/gu, '')
+            .toUpperCase();
+        const normalizedIdeology = ideology
+            ?.trim()
+            .replace(/[^A-Za-z0-9_]/gu, '')
+            .toLowerCase();
+        const spriteKey = (sprite?.name ?? slotName)?.toLocaleLowerCase('en-US') ?? 'plain';
+        const key = `${normalizedTag}:${normalizedIdeology ?? ''}:${spriteKey}`;
+        let promise = this.countryFlags.get(key);
+        if (promise !== undefined)
+            return promise;
+        promise = this.decodeCountryFlag(normalizedTag, sprite, normalizedIdeology, slotName);
+        this.countryFlags.set(key, promise);
+        return promise;
+    }
+    async decodeCountryFlag(tag, sprite, ideology, slotName) {
+        if (!/^[A-Z0-9_]{2,64}$/u.test(tag))
+            return {
+                spriteName: `GFX_flag_${tag || 'invalid'}`,
+                texturePath: '',
+                frame: 0,
+                frameCount: 1,
+                width: 0,
+                height: 0,
+                format: 'unknown',
+                supported: false,
+                reason: `Invalid country tag: ${tag || '<empty>'}`,
+            };
+        const normalizedSlotName = (sprite?.name ?? slotName)?.toLocaleLowerCase('en-US') ?? '';
+        const preferredDirectories = normalizedSlotName.includes('smallest')
+            ? ['small', 'medium', '']
+            : normalizedSlotName.includes('small')
+                ? ['medium', '', 'small']
+                : normalizedSlotName.includes('medium')
+                    ? ['medium', '', 'small']
+                    : ['', 'medium', 'small'];
+        const directories = [...new Set([...preferredDirectories, '', 'medium', 'small'])];
+        const ideologyCandidates = ideology === undefined ? ['democratic', 'neutrality', 'fascism', 'communism'] : [ideology];
+        const stems = [...ideologyCandidates.map((candidate) => `${tag}_${candidate}`), tag];
+        const maskedShield = sprite?.spriteType.toLocaleLowerCase('en-US') === 'maskedshieldtype';
+        const [overlay, mask] = maskedShield
+            ? await Promise.all([
+                sprite.texturePath === undefined
+                    ? undefined
+                    : this.loadRaster(sprite.texturePath, sprite.sourcePath),
+                sprite.texturePath2 === undefined
+                    ? undefined
+                    : this.loadRaster(sprite.texturePath2, sprite.sourcePath),
+            ])
+            : [undefined, undefined];
+        const targetRaster = mask?.supported === true ? mask : overlay?.supported === true ? overlay : undefined;
+        const candidates = [];
+        for (const directory of directories) {
+            for (const stem of stems) {
+                for (const extension of ['tga', 'png', 'dds', 'bmp']) {
+                    const candidate = this.resolveFile(`gfx/flags/${directory.length === 0 ? '' : `${directory}/`}${stem}.${extension}`);
+                    if (candidate !== undefined && !candidates.includes(candidate))
+                        candidates.push(candidate);
+                }
+            }
+        }
+        if (candidates.length === 0)
+            return {
+                spriteName: `GFX_flag_${tag}`,
+                texturePath: `gfx/flags/${tag}.tga`,
+                frame: 0,
+                frameCount: 1,
+                width: 0,
+                height: 0,
+                format: 'unknown',
+                supported: false,
+                reason: `Country flag texture not found for ${tag}.`,
+            };
+        let firstDecoded;
+        let selected;
+        for (const file of candidates) {
+            const raster = await this.loadRaster(file.relativePath);
+            firstDecoded ??= { file, raster };
+            if (!raster.supported)
+                continue;
+            selected ??= { file, raster };
+            if (raster.width === targetRaster?.width && raster.height === targetRaster.height) {
+                selected = { file, raster };
+                break;
+            }
+            if (targetRaster === undefined)
+                break;
+        }
+        const decoded = selected ?? firstDecoded;
+        const flagFile = decoded.file;
+        const flag = decoded.raster;
+        if (!flag.supported)
+            return {
+                spriteName: `GFX_flag_${tag}`,
+                texturePath: flagFile.relativePath,
+                frame: 0,
+                frameCount: 1,
+                width: flag.width,
+                height: flag.height,
+                format: flag.format,
+                supported: false,
+                ...(flag.reason === undefined ? {} : { reason: flag.reason }),
+            };
+        const width = targetRaster?.width ?? flag.width;
+        const height = targetRaster?.height ?? flag.height;
+        this.budget.reserveRasterOperation(`gui-country-flag:${flagFile.displayPath}:${sprite?.name ?? slotName ?? 'plain'}`, `GUI country flag rasterization ${tag}`);
+        this.budget.reserve(width, height, `GUI country flag ${tag}`, {
+            maximumPixels: RENDER_MAX_DECODED_PIXELS,
+        });
+        const flagPng = await sharp(flag.data, {
+            raw: { width: flag.width, height: flag.height, channels: 4 },
+            limitInputPixels: RENDER_MAX_DECODED_PIXELS,
+        })
+            .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+            .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+            .toBuffer();
+        const composites = [];
+        if (mask?.supported === true) {
+            const maskPixels = await sharp(mask.data, {
+                raw: { width: mask.width, height: mask.height, channels: 4 },
+                limitInputPixels: RENDER_MAX_DECODED_PIXELS,
+            })
+                .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+                .raw()
+                .toBuffer();
+            let alphaVaries = false;
+            const firstAlpha = maskPixels[3] ?? 255;
+            for (let offset = 7; offset < maskPixels.length; offset += 4) {
+                if (maskPixels[offset] !== firstAlpha) {
+                    alphaVaries = true;
+                    break;
+                }
+            }
+            const alphaMask = Buffer.alloc(maskPixels.length);
+            for (let offset = 0; offset < maskPixels.length; offset += 4) {
+                alphaMask[offset] = 255;
+                alphaMask[offset + 1] = 255;
+                alphaMask[offset + 2] = 255;
+                alphaMask[offset + 3] = alphaVaries
+                    ? maskPixels[offset + 3]
+                    : Math.round(maskPixels[offset] * 0.2126 +
+                        maskPixels[offset + 1] * 0.7152 +
+                        maskPixels[offset + 2] * 0.0722);
+            }
+            composites.push({
+                input: await sharp(alphaMask, {
+                    raw: { width, height, channels: 4 },
+                    limitInputPixels: RENDER_MAX_DECODED_PIXELS,
+                })
+                    .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                    .toBuffer(),
+                blend: 'dest-in',
+            });
+        }
+        if (overlay?.supported === true)
+            composites.push({
+                input: await sharp(overlay.data, {
+                    raw: { width: overlay.width, height: overlay.height, channels: 4 },
+                    limitInputPixels: RENDER_MAX_DECODED_PIXELS,
+                })
+                    .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+                    .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                    .toBuffer(),
+                blend: 'over',
+            });
+        const png = composites.length === 0
+            ? flagPng
+            : await sharp(flagPng, { limitInputPixels: RENDER_MAX_DECODED_PIXELS })
+                .composite(composites)
+                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                .toBuffer();
+        return {
+            spriteName: `GFX_flag_${tag}`,
+            texturePath: flagFile.relativePath,
+            frame: 0,
+            frameCount: 1,
+            width,
+            height,
+            dataUri: `data:image/png;base64,${png.toString('base64')}`,
+            format: flag.format,
+            supported: true,
+        };
+    }
     loadSpriteTextureFrame(sprite, texturePath, requestedFrame, layer) {
         if (texturePath === undefined)
             return Promise.resolve(undefined);
@@ -471,7 +659,9 @@ export class GuiAssetCatalog {
                 if (previous !== undefined)
                     penX += (entry.bmfont.kerning.get(`${previous}:${codePoint}`) ?? 0) * scale;
                 const pagePath = entry.bmfont.pages[metric.page];
-                const pageFile = pagePath === undefined ? undefined : this.resolveBmFontPage(entry, pagePath, metric.page);
+                // Older shipped HOI4 descriptors omit the page record entirely. Page zero still uses the
+                // descriptor stem (for example garamond_12.fnt -> garamond_12.dds/tga).
+                const pageFile = this.resolveBmFontPage(entry, pagePath ?? '', metric.page);
                 const raster = pageFile === undefined
                     ? undefined
                     : await this.loadBmFontGlyph(entry, pageFile, metric, codePoint);
@@ -619,26 +809,104 @@ export class GuiAssetCatalog {
                     .raw()
                     .toBuffer({ resolveWithObject: true });
                 const channelRoles = entry.bmfont?.channelRoles;
-                let facePixels = extracted.data;
+                const channelRanges = [0, 1, 2, 3].map((channel) => {
+                    let minimum = 255;
+                    let maximum = 0;
+                    for (let offset = channel; offset < extracted.data.length; offset += 4) {
+                        const sample = extracted.data[offset] ?? 0;
+                        minimum = Math.min(minimum, sample);
+                        maximum = Math.max(maximum, sample);
+                    }
+                    return maximum - minimum;
+                });
+                const channelActivePixels = [0, 1, 2, 3].map((channel) => {
+                    let active = 0;
+                    for (let offset = channel; offset < extracted.data.length; offset += 4)
+                        if ((extracted.data[offset] ?? 0) > 0)
+                            active += 1;
+                    return active;
+                });
+                const channelSelected = (channel) => {
+                    if (metric.channelMask === 15)
+                        return true;
+                    const maskForChannel = [4, 2, 1, 8][channel] ?? 0;
+                    return (metric.channelMask & maskForChannel) !== 0;
+                };
+                const informativeChannels = (role) => channelRoles === undefined
+                    ? []
+                    : channelRoles
+                        .map((candidate, channel) => ({ candidate, channel }))
+                        .filter(({ candidate, channel }) => candidate === role &&
+                        channelSelected(channel) &&
+                        (channelRanges[channel] ?? 0) > 0)
+                        .map(({ channel }) => channel);
+                const alphaIsInformative = (channelRanges[3] ?? 0) > 0;
+                let faceChannels = informativeChannels(0);
+                let borderChannels = informativeChannels(1);
+                const undeclaredRgbFaceChannels = channelRoles === undefined
+                    ? []
+                    : [0, 1, 2].filter((channel) => channelRoles[channel] === 4 &&
+                        (channelRanges[channel] ?? 0) > 0 &&
+                        (channelActivePixels[channel] ?? 0) > 0);
+                const undeclaredRgbChannelsAgree = undeclaredRgbFaceChannels.every((channel) => channel === undeclaredRgbFaceChannels[0] ||
+                    extracted.data.every((sample, offset) => offset % 4 !== channel ||
+                        sample ===
+                            extracted.data[offset - channel + (undeclaredRgbFaceChannels[0] ?? channel)]));
+                if (faceChannels.includes(3) &&
+                    borderChannels.length === 0 &&
+                    undeclaredRgbFaceChannels.length > 0 &&
+                    undeclaredRgbChannelsAgree) {
+                    const rgbFace = undeclaredRgbFaceChannels[0];
+                    const rgbPixels = channelActivePixels[rgbFace] ?? 0;
+                    const alphaPixels = channelActivePixels[3] ?? 0;
+                    if (rgbPixels * 1.15 < alphaPixels) {
+                        // Some shipped HOI4 descriptors label RGB as constant even though RGB stores the
+                        // thin face and alpha stores the wider face-plus-outline mask. Trusting the declared
+                        // alpha role paints the outline in the face colour and visibly fattens the font.
+                        faceChannels = [rgbFace];
+                        borderChannels = [3];
+                    }
+                }
+                if (faceChannels.length === 0) {
+                    if (borderChannels.length > 0) {
+                        // Some vanilla fonts declare their only useful alpha bitmap as the outline
+                        // channel even though the atlas contains no separate face channel. In that case
+                        // the alpha bitmap is the face; treating constant-white RGB as coverage produces
+                        // an opaque rectangle for every glyph.
+                        faceChannels = borderChannels;
+                        borderChannels = [];
+                    }
+                    else {
+                        faceChannels = alphaIsInformative
+                            ? [3]
+                            : channelRanges
+                                .map((range, channel) => ({ range, channel }))
+                                .filter(({ range }) => range > 0)
+                                .map(({ channel }) => channel);
+                    }
+                }
+                const facePixels = Buffer.alloc(extracted.data.length);
                 let borderPixels;
-                if (channelRoles?.some((role) => role === 0) === true) {
-                    facePixels = Buffer.alloc(extracted.data.length);
-                    borderPixels = channelRoles.some((role) => role === 1)
-                        ? Buffer.alloc(extracted.data.length)
-                        : undefined;
+                if (faceChannels.length > 0) {
+                    borderPixels =
+                        borderChannels.length > 0 ? Buffer.alloc(extracted.data.length) : undefined;
                     // BMFont role 0 is coverage, not a per-glyph light/dark bitmap. Vanilla atlases may
                     // contain glyphs with either more filled or more empty pixels, so polarity inference
                     // from an individual crop corrupts neighboring letters inconsistently.
                     for (let offset = 0; offset < extracted.data.length; offset += 4) {
                         let faceCoverage = 0;
                         let borderCoverage = 0;
-                        for (let channel = 0; channel < 4; channel += 1) {
+                        for (const channel of faceChannels) {
                             const sample = extracted.data[offset + channel] ?? 0;
-                            if (channelRoles[channel] === 0)
-                                faceCoverage = Math.max(faceCoverage, sample);
-                            if (channelRoles[channel] === 1)
-                                borderCoverage = Math.max(borderCoverage, sample);
+                            faceCoverage = Math.max(faceCoverage, sample);
                         }
+                        for (const channel of borderChannels)
+                            borderCoverage = Math.max(borderCoverage, extracted.data[offset + channel] ?? 0);
+                        // Vanilla's compressed multi-channel atlases can bleed a neighboring glyph into
+                        // an RGB face crop while the alpha silhouette remains correctly bounded. The
+                        // face is the intersection, not the union, of those declared layers.
+                        if (borderChannels.length > 0)
+                            faceCoverage = Math.min(faceCoverage, borderCoverage);
                         facePixels[offset] = 255;
                         facePixels[offset + 1] = 255;
                         facePixels[offset + 2] = 255;

package/dist/hoi4_agent_tools/gui/layout.js

@@ -570,6 +570,41 @@ function anchoredCoordinate(start, span, offset, anchor) {
             ? start + span / 2 + offset
             : start + offset;
 }
+function dynamicCountryFlag(elementName, expression, scenario, rowValues) {
+    if (typeof expression !== 'string')
+        return undefined;
+    const match = /^\[\?([^\]|]+)(?:\|[^\]]+)?\]$|^\[([^\]]+)\]$/u.exec(expression);
+    const token = match?.[1] ?? match?.[2];
+    const shortToken = token?.slice(token.lastIndexOf('.') + 1);
+    const tagCandidates = [
+        rowValues?.[`${elementName}.countryTag`],
+        rowValues?.countryTag,
+        rowValues?.GetTag,
+        rowValues?.tag,
+        scenario.values[`${elementName}.countryTag`],
+        scenario.values[`${elementName}.tag`],
+        token === undefined ? undefined : scenario.values[token],
+        shortToken === undefined ? undefined : scenario.values[shortToken],
+        scenario.scriptedGui[`${elementName}.countryTag`],
+        scenario.country?.countryTag,
+        scenario.country?.GetTag,
+        scenario.country?.tag,
+    ];
+    const rawTag = tagCandidates.find((candidate) => typeof candidate === 'string' && /^[A-Za-z0-9_]{2,64}$/u.test(candidate));
+    if (rawTag === undefined)
+        return undefined;
+    const ideologyCandidates = [
+        rowValues?.[`${elementName}.ideology`],
+        rowValues?.ideology,
+        rowValues?.countryIdeology,
+        scenario.values[`${elementName}.ideology`],
+        scenario.values[`${elementName}.countryIdeology`],
+        scenario.country?.ideology,
+        scenario.country?.countryIdeology,
+    ];
+    const ideology = ideologyCandidates.find((candidate) => typeof candidate === 'string' && /^[A-Za-z0-9_]{2,64}$/u.test(candidate));
+    return { tag: rawTag, ...(ideology === undefined ? {} : { ideology }) };
+}
 class GuiSceneWorkBudget {
     work = 0;
     elements = 0;
@@ -643,6 +678,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
         0;
     let width = scaledNumber(size === undefined ? undefined : property(size, 'width', 'x'), parentRect.width, scale) ?? 0;
     let height = scaledNumber(size === undefined ? undefined : property(size, 'height', 'y'), parentRect.height, scale) ?? 0;
+    const scriptedVisible = rowValues?.[`${definition.name}.visible`] ??
+        scenario.values[`${definition.name}.visible`] ??
+        scenario.scriptedGui[`${definition.name}.visible`];
+    const explicitlyVisible = scenario.visibility[definition.name] ??
+        scenario.visibility[definition.id] ??
+        (typeof scriptedVisible === 'boolean' ? scriptedVisible : undefined);
+    const resolveVisibleAppearance = inheritedVisible && explicitlyVisible !== false;
     const background = objectProperty(property(definition.attributes, 'background'));
     const scriptedImage = rowValues?.[`${definition.name}.image`] ??
         rowValues?.[definition.name] ??
@@ -659,7 +701,23 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     let sprite;
     let secondarySprite;
     let spriteRenderMode;
-    if (spriteName !== undefined && spriteDefinition === undefined) {
+    const countryFlag = dynamicCountryFlag(definition.name, context.countryFlagProperties.get(definition.name), scenario, rowValues);
+    if (countryFlag !== undefined && resolveVisibleAppearance) {
+        sprite = await catalog.loadCountryFlag(countryFlag.tag, spriteDefinition, countryFlag.ideology, spriteName);
+        spriteRenderMode = 'stretch';
+        if (sprite.supported) {
+            if (width === 0)
+                width = sprite.width * scale;
+            if (height === 0)
+                height = sprite.height * scale;
+            addFidelity(fidelity, 'modelled', 'dynamic_country_flag', `${definition.name} resolved the ${countryFlag.tag} flag from scenario country context.`, definition);
+        }
+        else {
+            addFidelity(fidelity, 'missing', 'dynamic_country_flag', sprite.reason ?? `Country flag ${countryFlag.tag} could not be rendered.`, definition);
+            diagnostics.push(diagnostic('GUI_COUNTRY_FLAG_MISSING', 'warning', sprite.reason ?? `Country flag ${countryFlag.tag} could not be rendered.`, definition));
+        }
+    }
+    else if (spriteName !== undefined && spriteDefinition === undefined) {
         const partialInventory = context.graph.edges.some((edge) => edge.kind === 'uses_sprite' &&
             edge.from === definition.id &&
             !edge.resolved &&
@@ -669,7 +727,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             ? `The partial GUI inventory cannot resolve sprite ${spriteName} for ${definition.name}; a skipped source could define it.`
             : `Element ${definition.name} references missing sprite ${spriteName}.`, definition));
     }
-    else if (spriteDefinition !== undefined) {
+    else if (spriteDefinition !== undefined && resolveVisibleAppearance) {
         const partialAppearance = [];
         const spriteType = spriteDefinition.spriteType.toLowerCase();
         spriteRenderMode =
@@ -740,7 +798,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const embeddedButtonText = rawText !== undefined &&
         (rawButtonText !== undefined || definition.elementType.toLowerCase().includes('button'));
     let text;
-    if (rawText !== undefined) {
+    if (rawText !== undefined && resolveVisibleAppearance) {
         const resolved = resolveTokenText(rawText, scenario, context.localisation, rowValues);
         let displayText = resolved.text;
         const state = scenario.elementStates[definition.name] ?? scenario.state;
@@ -888,12 +946,6 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const clipRect = inheritedClip;
     const clipped = clipRect !== undefined &&
         (availableClip === undefined || !equalRect(unclippedRect, availableClip));
-    const scriptedVisible = rowValues?.[`${definition.name}.visible`] ??
-        scenario.values[`${definition.name}.visible`] ??
-        scenario.scriptedGui[`${definition.name}.visible`];
-    const explicitlyVisible = scenario.visibility[definition.name] ??
-        scenario.visibility[definition.id] ??
-        (typeof scriptedVisible === 'boolean' ? scriptedVisible : undefined);
     const visible = inheritedVisible &&
         (explicitlyVisible ?? (availableClip !== undefined || inheritedClip === undefined));
     const clickThrough = scalarBoolean(property(definition.attributes, 'clickThrough', 'alwaystransparent', 'allwaystransparent')) ?? false;
@@ -1141,6 +1193,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const constantElementEnabled = {};
     const resolvedScriptedProperties = {};
     const dynamicListsByName = new Map();
+    const countryFlagProperties = new Map();
     for (const scripted of graph.scriptedGuis.filter(({ name }) => relevantScriptedGuiNames.has(name))) {
         for (const dynamicList of scripted.dynamicListDefinitions)
             dynamicListsByName.set(dynamicList.name, dynamicList);
@@ -1149,6 +1202,13 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
                 const suffix = attribute.toLowerCase();
                 if (!['image', 'frame', 'x', 'y', 'visible', 'enabled'].includes(suffix))
                     continue;
+                const countryFlagExpression = suffix === 'image' &&
+                    typeof expression === 'string' &&
+                    /(?:^|\.)GetFlag\]$/u.test(expression);
+                if (countryFlagExpression)
+                    countryFlagProperties.set(propertyDefinition.elementName, expression);
+                if (countryFlagExpression)
+                    continue;
                 const resolved = scenarioExpressionValue(expression, scenario.values);
                 if (resolved === undefined)
                     continue;
@@ -1210,6 +1270,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         elementsById,
         elementsByName,
         dynamicListsByName,
+        countryFlagProperties,
         constantElementEnabled,
         spritesByName: new Map(graph.sprites.map((sprite) => [sprite.name.toLowerCase(), sprite])),
         localisation,

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -60,7 +60,7 @@ function sceneGlyphDefinitions(scene) {
             .map(([key, glyphPath]) => `<path id="${outlineDefinitionId(key)}" d="${glyphPath}"/>`),
         ...[...bitmaps.entries()]
             .sort(([left], [right]) => compareCodeUnits(left, right))
-            .map(([key, glyph]) => `<image id="${bitmapDefinitionId(key)}" width="${finite(glyph.width)}" height="${finite(glyph.height)}" href="${glyph.dataUri}" preserveAspectRatio="none"/>${glyph.borderDataUri === undefined ? '' : `<image id="${bitmapDefinitionId(key, 'border')}" width="${finite(glyph.width)}" height="${finite(glyph.height)}" href="${glyph.borderDataUri}" preserveAspectRatio="none"/>`}`),
+            .map(([key, glyph]) => `<image id="${bitmapDefinitionId(key)}" width="${finite(glyph.width)}" height="${finite(glyph.height)}" href="${glyph.dataUri}" preserveAspectRatio="none" image-rendering="optimizeSpeed"/>${glyph.borderDataUri === undefined ? '' : `<image id="${bitmapDefinitionId(key, 'border')}" width="${finite(glyph.width)}" height="${finite(glyph.height)}" href="${glyph.borderDataUri}" preserveAspectRatio="none" image-rendering="optimizeSpeed"/>`}`),
     ].join('');
 }
 function bitmapTintMarkup(id, colour, glyphs, rect) {
@@ -87,7 +87,13 @@ function actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale, bitmap
         return glyphLine.glyphs
             .filter((glyph) => glyph.kind === 'bitmap')
             .filter((glyph) => bitmapLayer === 'face' || glyph.borderDataUri !== undefined)
-            .map((glyph) => `<use href="#${bitmapDefinitionId(glyph.key, bitmapLayer)}" transform="translate(${finite(originX + glyph.x * horizontalScale)} ${finite(baseline + glyph.y - glyphLine.baseline)}) scale(${finite(horizontalScale)} 1)"/>`)
+            .map((glyph) => {
+            const nativePixelGrid = Math.abs(horizontalScale - 1) < 0.000_001 &&
+                [glyph.x, glyph.y, glyph.width, glyph.height, glyphLine.baseline].every((value) => Math.abs(value - Math.round(value)) < 0.000_001);
+            const x = originX + glyph.x * horizontalScale;
+            const y = baseline + glyph.y - glyphLine.baseline;
+            return `<use href="#${bitmapDefinitionId(glyph.key, bitmapLayer)}" transform="translate(${finite(nativePixelGrid ? Math.round(x) : x)} ${finite(nativePixelGrid ? Math.round(y) : y)}) scale(${finite(horizontalScale)} 1)"/>`;
+        })
             .join('');
     return '';
 }
@@ -399,16 +405,23 @@ function viewFor(scene, variant) {
         };
     }
     const padding = 16;
-    const x = Math.max(0, scene.bounds.x - padding);
-    const y = Math.max(0, scene.bounds.y - padding);
-    const right = Math.min(scene.resolution.width, scene.bounds.x + scene.bounds.width + padding);
-    const bottom = Math.min(scene.resolution.height, scene.bounds.y + scene.bounds.height + padding);
+    const x = Math.floor(Math.max(0, scene.bounds.x - padding));
+    const y = Math.floor(Math.max(0, scene.bounds.y - padding));
+    const right = Math.ceil(Math.min(scene.resolution.width, scene.bounds.x + scene.bounds.width + padding));
+    const bottom = Math.ceil(Math.min(scene.resolution.height, scene.bounds.y + scene.bounds.height + padding));
     return {
         viewBox: { x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) },
         width: Math.max(1, Math.ceil(right - x)),
         height: Math.max(1, Math.ceil(bottom - y)),
     };
 }
+function overlayToSvg(scene, variant) {
+    const toolText = new DeterministicSvgTextRenderer();
+    const overlays = scene.elements
+        .map((element) => renderOverlay(element, variant, toolText))
+        .join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${scene.resolution.width}" height="${scene.resolution.height}" viewBox="0 0 ${scene.resolution.width} ${scene.resolution.height}"><defs>${toolText.definitions()}</defs>${overlays}</svg>`;
+}
 export function sceneToSvg(scene, variant) {
     const view = viewFor(scene, variant);
     assertRenderDimensions(view.width, view.height, `GUI ${variant} SVG`);
@@ -548,7 +561,7 @@ export async function renderGuiScene(scene, variants = defaultVariants, signal,
     if (scene.elements.length > GUI_SCENE_MAX_ELEMENTS) {
         throw new ServiceError('GUI_RENDER_ELEMENT_BUDGET_BLOCKED', 'GUI scene exceeds the fixed render element ceiling', { elements: scene.elements.length, maximumElements: GUI_SCENE_MAX_ELEMENTS });
     }
-    const images = [];
+    const prepared = [];
     for (const variant of variants) {
         signal?.throwIfAborted();
         const view = viewFor(scene, variant);
@@ -556,13 +569,69 @@ export async function renderGuiScene(scene, variants = defaultVariants, signal,
         const svg = signal === undefined
             ? sceneToSvg(scene, variant)
             : await sceneToSvgCooperative(scene, variant, signal);
-        assertRenderDimensions(view.width, view.height, `GUI ${variant} Sharp raster`);
-        budget.reserveRasterOperation(`gui-variant:${sha256Bytes(svg)}`, `GUI ${variant} SVG rasterization`);
-        const png = await sharp(Buffer.from(svg), { limitInputPixels: RENDER_MAX_PIXELS })
+        prepared.push({ variant, view, svg });
+    }
+    const full = prepared.find(({ variant }) => variant === 'full');
+    let images;
+    if (full === undefined) {
+        images = [];
+        for (const item of prepared) {
+            assertRenderDimensions(item.view.width, item.view.height, `GUI ${item.variant} Sharp raster`);
+            budget.reserveRasterOperation(`gui-variant:${sha256Bytes(item.svg)}`, `GUI ${item.variant} SVG rasterization`);
+            const png = await sharp(Buffer.from(item.svg), { limitInputPixels: RENDER_MAX_PIXELS })
+                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                .toBuffer();
+            signal?.throwIfAborted();
+            images.push({
+                variant: item.variant,
+                svg: item.svg,
+                png,
+                width: item.view.width,
+                height: item.view.height,
+            });
+        }
+    }
+    else {
+        assertRenderDimensions(full.view.width, full.view.height, 'GUI full Sharp raster');
+        budget.reserveRasterOperation(`gui-variant:${sha256Bytes(full.svg)}`, 'GUI full SVG rasterization');
+        const basePng = await sharp(Buffer.from(full.svg), { limitInputPixels: RENDER_MAX_PIXELS })
             .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
             .toBuffer();
-        signal?.throwIfAborted();
-        images.push({ variant, svg, png, width: view.width, height: view.height });
+        const rendered = await Promise.all(prepared.map(async (item) => {
+            if (item.variant === 'full')
+                return {
+                    variant: item.variant,
+                    svg: item.svg,
+                    png: basePng,
+                    width: item.view.width,
+                    height: item.view.height,
+                };
+            signal?.throwIfAborted();
+            budget.reserveRasterOperation(`gui-derived-variant:${sha256Bytes(item.svg)}`, `GUI ${item.variant} derived rasterization`);
+            const png = item.variant === 'cropped'
+                ? await sharp(basePng, { limitInputPixels: RENDER_MAX_PIXELS })
+                    .extract({
+                    left: item.view.viewBox.x,
+                    top: item.view.viewBox.y,
+                    width: item.view.width,
+                    height: item.view.height,
+                })
+                    .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                    .toBuffer()
+                : await sharp(basePng, { limitInputPixels: RENDER_MAX_PIXELS })
+                    .composite([{ input: Buffer.from(overlayToSvg(scene, item.variant)) }])
+                    .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                    .toBuffer();
+            signal?.throwIfAborted();
+            return {
+                variant: item.variant,
+                svg: item.svg,
+                png,
+                width: item.view.width,
+                height: item.view.height,
+            };
+        }));
+        images = rendered;
     }
     return {
         scene,