Testing, import and updates

ZIP import in the admin panel

In the admin panel's templates section, choose ZIP import. This requires the templates.import permission. A valid package becomes a draft with the testing status; uploading does not publish the theme or change existing customer pages.

ZIP package structure

An admin import package contains archive.json, GS Loom sources in theme/, and additional files in assets/ when needed. Put these directly at the ZIP root or inside one enclosing folder:

noir-explorer/
├── archive.json
├── theme/
│   ├── loom.json
│   ├── layout/
│   ├── templates/
│   ├── sections/
│   ├── blocks/
│   ├── config/
│   └── locales/
└── assets/
    └── blog.css

The theme/ directory must contain a complete, valid theme, including loom.json. This tree illustrates the archive layout rather than every theme file. Do not add another enclosing folder or unrelated files such as .DS_Store and __MACOSX.

What archive.json contains

archive.json describes the archive format and GrowSite product configuration. Place it next to theme/. It does not replace theme/loom.json or section and block schema files.

Example for Noir Explorer:

{
  "format": "gs-loom-archive",
  "version": 1,
  "configuration": {
    "key": "noir-explorer",
    "name": "Noir Explorer",
    "version": "1.0.0",
    "tier": "basic",
    "supports_blog": true,
    "price_cents": 0,
    "default_settings": {},
    "schema": {}
  }
}

Preparing packages and troubleshooting

Start with the GrowSite Skeleton ZIP, which includes archive.json. The Launch Theme ZIP contains sources for local development: to import it through the panel, move the theme directory's contents into theme/ and add a valid archive.json beside it.

The upload limit is 24 MiB. An archive may contain up to 5000 entries, up to 48,000,000 uncompressed bytes in total and up to 25,000,000 bytes per file. Symbolic links and . or .. path segments are rejected.

Import a new package

Run these commands from the repository root, using your real directory path:

npm run loom:import -- /absolute/path/launch-theme
npm run themes:build
npm run themes:check
npm run loom:test
npm run themes:test
npm run build:customer
npm run build:renderer

Then synchronize products from the api directory:

php artisan themes:sync --activate

Import refuses an existing key. themes:build updates both the Loom registry and catalog. themes:check detects stale generated data. Synchronization activates new products with --activate, preserves existing product prices/status and does not overwrite customer page content.

Source import from the terminal requires repository access. ZIP import in the panel is available to authorized administrators; it is not a public marketplace submission workflow.

Update a theme

Increase the manifest version, for example from 1.0.0 to 1.0.1:

npm run loom:update -- /absolute/path/launch-theme
npm run themes:build
npm run themes:check
npm run build:customer
npm run build:renderer

The update command requires a higher numeric version and refuses removed existing sections, blocks, page templates or settings, and incompatible setting type changes. This is a compatibility guard, not a visual regression guarantee. Changing markup, CSS, defaults or targeting may still alter a saved page.

Directly editing installed source and running themes:build bypasses the import/update compatibility gate. Use the update command for distributed package releases. Preserve a source revision and deployment artifact so a failed release can be rolled back together with its generated registries.

Validation checklist

Additional renderer tests from the repository root:

node --test scripts/paylio-renderer.test.mjs scripts/theme-renderer.test.mjs

API validation tests, from api:

php artisan test --compact --filter=loom_theme_settings
php artisan test --compact tests/Feature/LoomDocumentTest.php

Diagnose common failures

Read the supported scope before extending a theme.