Extract before overriding
Package archives can be inspected as ZIP-compatible files. Extract the exact resource into a read-only originals directory, preserve its virtual path, and copy only intentional modifications into the build. This makes update comparisons possible and avoids replacing unrelated resources.
The complete extraction and staging workflow is documented in Tooling, Assets & Packaging.
Resource and cache invalidation
Generated resource accessors, native declarations or legacy maps, localization namespaces, and packaged files are separate layers. A successful filesystem lookup does not prove that the client UI can resolve the same asset. Use Resource & Cache Invalidation for the cross-system restart and reload matrix.
| Layer | What to verify | Failure symptom |
|---|---|---|
| Packaged file | The file exists in the archive at the expected path and case. | Works locally but not in the client. |
| Resource map | The virtual root maps to the packaged asset. | coui:// or UI resource load fails. |
| Generated accessor | The accessor name exists in the current build. | Python lookup fails after an update. |
| Localization namespace | The key exists and has a fallback for missing regions. | Raw key or empty text is displayed. |
| Runtime cache | The client has reloaded or restarted after registration changes. | Old CSS, JS, image, or text remains visible. |
Locale fonts and script readiness
Keep translation keys/arguments and client language explicit at the payload boundary, then resolve custom labels in one presentation catalog. Normalize regional aliases, provide key-by-key fallback and retain placeholder parity. Native-localized values should not be translated twice.
A separately injected localization script and renderer do not gain dependency ordering from an array of URLs. Use an explicit module dependency or bounded lazy catalog readiness. Native locale CSS can switch font families; explicit font rules on owned controls bypass that inherited override. Verify actual glyph output and restrict locale styling to owned elements.
See injection dependencies and frontend capabilities. Module evaluation, translation readiness and font rendering are separate gates.
Template reload can retain omitted keys
XMLCollection.load(clear=True) requests ResMgr.purge before opening its resource when no section is supplied. It does not clear the Python template dictionary. Loaded keys overwrite entries individually; keys omitted by the new input retain their old templates or cached missing-key placeholders. A missing resource or namespace also leaves the existing mapping intact.
Supplying a section bypasses resource opening and purging, even with clear=True. Collection.unload() is the distinct dictionary-clear operation. Keep resource invalidation, dictionary replacement and view refresh separate when defining an owned reload policy. The GUI template cache retains each collection, and its existing _reload_ht helper calls load(clear=True) only under the development-build gate; this does not establish a production hot-reload trigger.
Selected readable classes with inert resource/section, translation and logging substitutes confirmed overwrite versus retention, missing-source retention, supplied-section bypass and explicit unload. No XML assets, real resource opening or native cache invalidation, translation catalog, rendering or client runtime was exercised. The checks establish requested calls and Python mapping behavior, not fresh native resource contents.