### Local Setup with Make

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/README.md

Instructions for setting up and running the Omeka S Playground locally using make commands. This includes cloning the repository, installing dependencies, and starting the local development server.

```bash
git clone https://github.com/ateeducacion/omeka-s-playground.git
cd omeka-s-playground
make up
```

--------------------------------

### Preview Documentation Locally (Python/MkDocs)

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/docs/development.md

Steps to set up a Python virtual environment, install documentation dependencies, and serve the documentation site locally using MkDocs.

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-docs.txt
mkdocs serve
```

--------------------------------

### Bootstrap Omeka Installation - JavaScript

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

The `bootstrapOmeka` function orchestrates the complete Omeka S installation and configuration process within the browser runtime. It handles mounting core files, applying blueprint settings, installing modules and themes, creating users, and provisioning sample content. It requires an initialized PHP runtime, a normalized blueprint, and configuration details. A progress callback can be provided for UI updates. Dependencies include `bootstrapOmeka` from './src/runtime/bootstrap.js' and `normalizeBlueprint` from './src/shared/blueprint.js'.

```javascript
import { bootstrapOmeka } from './src/runtime/bootstrap.js';
import { normalizeBlueprint } from './src/shared/blueprint.js';

const config = await fetch('./playground.config.json').then(r => r.json());
const blueprint = normalizeBlueprint(myBlueprint, config);

// Progress callback for UI updates
const publish = (message, progress) => {
  console.log(`[${Math.round(progress * 100)}%] ${message}`);
};

// Bootstrap the Omeka installation
const result = await bootstrapOmeka({
  php,                    // Initialized PHP runtime
  blueprint,              // Normalized blueprint
  config,                 // Playground configuration
  runtimeId: 'php83',     // Runtime identifier
  clean: false,           // Set true to reset persisted state
  publish                 // Progress callback
});

// Result contains:
// {
//   manifest: { ... },      // Bundle manifest
//   manifestState: { ... }, // State for version tracking
//   readyPath: '/admin'     // Landing path after bootstrap
// }

console.log(`Omeka ready at ${result.readyPath}`);
```

--------------------------------

### Manage Local Development Environment

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

A set of Makefile commands to manage the Omeka S Playground development lifecycle, including dependency installation, bundling, and server execution. These commands simplify common tasks like linting, testing, and environment setup.

```bash
git clone https://github.com/ateeducacion/omeka-s-playground.git
cd omeka-s-playground

make up

make deps
make prepare
make bundle
make serve
make test
make lint
make format
make clean

PORT=9090 make serve

OMEKA_REF=https://github.com/yourfork/omeka-s.git \
OMEKA_REF_BRANCH=your-branch \
make bundle
```

--------------------------------

### Install Omeka S Addons via Blueprint

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

Demonstrates how to define a blueprint containing modules and themes from various sources such as bundled files, omeka.org slugs, or direct URLs. The materializeBlueprintAddons function processes these specifications to download, extract, and mount the addons into the Omeka root directory.

```javascript
import { materializeBlueprintAddons } from './src/runtime/addons.js';

const blueprint = {
  modules: [
    { name: "Mapping", state: "activate", source: { type: "bundled" } },
    { name: "CSVImport", state: "activate", source: { type: "omeka.org", slug: "csv-import" } },
    { name: "CustomVocab", state: "install", source: { type: "url", url: "https://github.com/omeka-s-modules/CustomVocab/releases/download/v2.0.0/CustomVocab-2.0.0.zip" } }
  ],
  themes: [
    { name: "Foundation", source: { type: "omeka.org", slug: "foundation-s" } },
    { name: "CustomTheme", source: { type: "url", url: "https://example.com/theme.zip" } }
  ]
};

const result = await materializeBlueprintAddons({
  php,
  blueprint,
  omekaRoot: '/www/omeka',
  config,
  publish: (msg, p) => console.log(msg)
});
```

--------------------------------

### Omeka S Playground Configuration (JSON)

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/README.md

This JSON configuration file defines the setup for an Omeka S instance within the playground. It specifies schema, debugging, landing page, site options, user roles, module activations, item sets, and item media. It serves as the blueprint for initializing the Omeka S environment.

```json
{
  "$schema": "./assets/blueprints/blueprint-schema.json",
  "debug": { "enabled": true },
  "landingPage": "/s/demo",
  "siteOptions": {
    "title": "Demo Omeka",
    "locale": "es",
    "timezone": "Atlantic/Canary"
  },
  "users": [
    { "username": "admin", "email": "admin@example.com", "password": "password", "role": "global_admin" }
  ],
  "modules": [
    { "name": "CSVImport", "state": "activate" },
    {
      "name": "Mapping",
      "state": "activate",
      "source": { "type": "url", "url": "https://example.com/Mapping.zip" }
    }
  ],
  "itemSets": [{ "title": "Demo Collection" }],
  "items": [
    {
      "title": "Landscape sample",
      "itemSets": ["Demo Collection"],
      "media": [{ "type": "url", "url": "https://example.com/photo.jpg", "title": "Photo" }]
    }
  ],
  "site": {
    "title": "Demo Site",
    "slug": "demo",
    "theme": "default",
    "setAsDefault": true
  }
}
```

--------------------------------

### Make Targets for Omeka S Playground

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/README.md

A list of available make commands for managing the Omeka S Playground project, including tasks for setup, building, serving, testing, and cleaning.

```makefile
make up
# Install deps, build the Omeka bundle, and serve locally

make prepare
# Install npm deps, vendor browser assets, and bundle the PHP worker

make bundle
# Fetch Omeka, run Composer, build the ZIP bundle and manifest

make serve
# Start the local dev server on port 8080, including the addon download proxy

make test
# Run unit tests

make lint
# Check code with Biome

make format
# Auto-fix code with Biome

make clean
# Remove generated bundle, dist, and vendored runtime assets
```

--------------------------------

### Define Omeka S Playground Blueprint Configuration

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/docs/blueprint-json.md

This JSON structure defines the initial state of an Omeka S instance, including site metadata, admin credentials, themes, modules, and sample content. It is used by the system runtime to automate the first-boot installation process.

```json
{
  "$schema": "./assets/blueprints/blueprint-schema.json",
  "meta": {
    "title": "Demo classroom blueprint",
    "author": "ateeducacion",
    "description": "Creates a reusable demo site with sample media."
  },
  "debug": {
    "enabled": false
  },
  "landingPage": "/admin",
  "siteOptions": {
    "title": "Classroom Demo",
    "locale": "es",
    "timezone": "Atlantic/Canary"
  },
  "login": {
    "email": "admin@example.com",
    "password": "password"
  },
  "users": [
    {
      "username": "admin",
      "email": "admin@example.com",
      "password": "password",
      "role": "global_admin"
    }
  ],
  "themes": [
    {
      "name": "Foundation",
      "source": { "type": "omeka.org", "slug": "foundation-s" }
    }
  ],
  "modules": [
    { "name": "CSVImport", "state": "activate" }
  ],
  "itemSets": [
    { "title": "Playground Collection" }
  ],
  "items": [
    {
      "title": "Openverse Sample Image",
      "itemSets": ["Playground Collection"],
      "media": [
        {
          "type": "url",
          "url": "./assets/samples/playground-sample.png",
          "title": "Playground sample image"
        }
      ]
    }
  ],
  "site": {
    "title": "Demo Site",
    "slug": "demo-site",
    "theme": "Foundation",
    "setAsDefault": true
  }
}
```

--------------------------------

### Build Documentation Locally (MkDocs)

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/docs/development.md

Command to build the static documentation site for the Omeka-S Playground locally using MkDocs in strict mode to catch errors early.

```bash
mkdocs build --strict
```

--------------------------------

### Loading Omeka S Blueprints via URL (Bash)

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

Demonstrates how to load Omeka S playground blueprints dynamically using URL parameters. This allows for sharing pre-configured instances without manual uploads, supporting both file paths and inline base64url-encoded JSON.

```bash
# Load blueprint from a URL path
https://ateeducacion.github.io/omeka-s-playground/?blueprint=/path/to/custom.blueprint.json

# Load blueprint from external URL
https://ateeducacion.github.io/omeka-s-playground/?blueprint=https://example.com/museum.blueprint.json

# Load blueprint inline with base64url encoding
# First, encode your blueprint JSON:
echo '{"landingPage":"/admin","siteOptions":{"title":"Quick Demo"}}' | base64 | tr '+/' '-_' | tr -d '=' 

# Then use in URL:
https://ateeducacion.github.io/omeka-s-playground/?blueprint-data=eyJsYW5kaW5nUGFnZSI6Ii9hZG1pbiIsInNpdGVPcHRpb25zIjp7InRpdGxlIjoiUXVpY2sgRGVtbyJ9fQ
```

--------------------------------

### Integrate Shell UI with Omeka Runtime

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

This JavaScript snippet demonstrates how to initialize the shell environment, establish a BroadcastChannel connection with the Omeka iframe, and handle lifecycle events. It includes logic for loading configurations, resolving blueprints, and exporting data.

```javascript
import { resolveBlueprintForShell, saveActiveBlueprint, clearActiveBlueprint, exportBlueprintPayload } from './src/shared/blueprint.js';
import { loadPlaygroundConfig } from './src/shared/config.js';
import { createShellChannel } from './src/shared/protocol.js';

const config = await loadPlaygroundConfig();
const scopeId = 'my-session-id';
const blueprint = await resolveBlueprintForShell(scopeId, config);

const channel = new BroadcastChannel(createShellChannel(scopeId));

channel.addEventListener('message', (event) => {
  switch (event.data.kind) {
    case 'progress':
      console.log(`Boot progress: ${event.data.detail}`);
      break;
    case 'ready':
      console.log(`Omeka ready at: ${event.data.path}`);
      break;
    case 'navigate':
      console.log(`Navigated to: ${event.data.path}`);
      break;
    case 'error':
      console.error('Runtime error:', event.data.detail);
      break;
    case 'phpinfo':
      document.getElementById('phpinfo').innerHTML = event.data.html;
      break;
  }
});

const exportedPayload = exportBlueprintPayload(config, blueprint);
const blob = new Blob([JSON.stringify(exportedPayload, null, 2)], {
  type: 'application/json'
});

saveActiveBlueprint(scopeId, blueprint);
clearActiveBlueprint(scopeId);
```

--------------------------------

### Omeka S Playground Architecture Overview

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/README.md

A high-level overview of the Omeka S Playground's architecture, illustrating the interaction between the shell UI, runtime host, service worker, PHP worker, and the WebAssembly runtime.

```text
index.html          Shell UI (toolbar, address bar, log panel)
  └─ remote.html    Runtime host — registers the Service Worker
       ├─ sw.js     Intercepts requests → routes to PHP worker
       └─ php-worker.js (bundled via esbuild)
            └─ @php-wasm/web (WebAssembly, PHP 8.1–8.5)
                 ├─ Omeka core in writable MEMFS  (extracted from ZIP bundle)
                 └─ In-memory state                (SQLite + config + files in MEMFS)
```

--------------------------------

### Run Development Commands (Bash)

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/docs/development.md

A set of common bash commands used for managing dependencies, preparing the project, bundling assets, and serving the development environment for the Omeka-S Playground.

```bash
make deps
make prepare
make bundle
make serve
```

--------------------------------

### Omeka S Blueprint Configuration (JSON)

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

Defines the initial state of an Omeka S playground instance, including users, modules, themes, item collections, and site configuration. This JSON structure is loaded at boot time to set up the playground environment.

```json
{
  "$schema": "./assets/blueprints/blueprint-schema.json",
  "meta": {
    "title": "Museum Demo Blueprint",
    "author": "museum-team",
    "description": "Creates a museum demo with sample exhibits."
  },
  "debug": {
    "enabled": false
  },
  "landingPage": "/s/exhibits",
  "siteOptions": {
    "title": "Virtual Museum",
    "locale": "en_US",
    "timezone": "America/New_York"
  },
  "login": {
    "email": "curator@museum.org",
    "password": "securepass123"
  },
  "users": [
    {
      "username": "curator",
      "email": "curator@museum.org",
      "password": "securepass123",
      "role": "global_admin",
      "isActive": true
    },
    {
      "username": "contributor",
      "email": "contributor@museum.org",
      "password": "contrib123",
      "role": "editor",
      "isActive": true
    }
  ],
  "themes": [
    {
      "name": "Foundation",
      "source": { "type": "omeka.org", "slug": "foundation-s" }
    }
  ],
  "modules": [
    { "name": "Mapping", "state": "activate" },
    { "name": "CSVImport", "state": "install" },
    {
      "name": "CustomModule",
      "state": "activate",
      "source": { "type": "url", "url": "https://example.com/CustomModule.zip" }
    }
  ],
  "itemSets": [
    {
      "title": "Ancient Artifacts",
      "description": "Collection of artifacts from ancient civilizations"
    },
    {
      "title": "Modern Art",
      "description": "Contemporary artwork collection"
    }
  ],
  "items": [
    {
      "title": "Egyptian Scarab",
      "description": "A carved scarab beetle from the New Kingdom period",
      "creator": "Unknown Egyptian artisan",
      "itemSets": ["Ancient Artifacts"],
      "media": [
        {
          "type": "url",
          "url": "https://example.com/scarab.jpg",
          "title": "Scarab photograph",
          "altText": "Blue faience scarab beetle"
        }
      ]
    }
  ],
  "site": {
    "title": "Museum Exhibits",
    "slug": "exhibits",
    "theme": "Foundation",
    "summary": "Explore our digital collection of artifacts and artwork.",
    "isPublic": true,
    "setAsDefault": true
  }
}
```

--------------------------------

### Create PHP Runtime - JavaScript

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

The `createPhpRuntime` function initializes the WebAssembly PHP runtime, allowing for configurable PHP versions and settings. It returns a deferred object that requires a `refresh()` call before use. This function is essential for running PHP applications in the browser. Dependencies include the `createPhpRuntime` function from './src/runtime/php-loader.js'.

```javascript
import { createPhpRuntime } from './src/runtime/php-loader.js';

// Create runtime with specific PHP version
const php = createPhpRuntime('primary', {
  appBaseUrl: 'http://localhost:8080',
  phpVersion: '8.3',
  webRoot: '/www/omeka'
});

// Initialize the runtime (loads WASM)
await php.refresh();

// Now you can use the runtime
const response = await php.request(
  new Request('https://playground.internal/admin')
);
const html = await response.text();

// File operations
await php.writeFile('/www/omeka/test.txt', new TextEncoder().encode('Hello'));
const content = await php.readFile('/www/omeka/test.txt');
const info = await php.analyzePath('/www/omeka/config');

// Create directories
await php.mkdir('/persist/custom-data');
```

--------------------------------

### Implement Crash Recovery with Snapshot Manager

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

Shows how to use the snapshot manager to detect fatal WASM errors, hydrate the current state, and restore it into a new runtime instance. This ensures database and file persistence across runtime crashes.

```javascript
import { createSnapshotManager, isFatalWasmError, isSafeToReplay, formatErrorDetail } from './src/runtime/crash-recovery.js';

const snapshots = createSnapshotManager({ postShell: (msg) => console.log(`[${msg.kind}] ${msg.detail}`) });
snapshots.trackAddonDir('/www/omeka/modules/MyModule');

async function handleRequest(php, request) {
  const serializedRequest = { method: request.method, url: request.url, body: await request.text() };
  try {
    return await php.request(request);
  } catch (error) {
    if (isFatalWasmError(error)) {
      await snapshots.hydrate(php, '/persist/mutable/db/omeka.sqlite');
      const newPhp = createPhpRuntime('recovery', { phpVersion: '8.3' });
      await newPhp.refresh();
      const { restored, addonsRestored } = await snapshots.restore(newPhp);
      if (isSafeToReplay(serializedRequest)) {
        return await newPhp.request(new Request(serializedRequest.url));
      }
      throw new Error('Non-idempotent request cannot be replayed after crash');
    }
    throw error;
  }
}
```

--------------------------------

### Configure Playground Runtime Settings

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

The playground.config.json file defines the global runtime parameters for the Omeka S Playground, including admin credentials, available PHP versions, and proxy settings. This file is essential for bootstrapping the application environment.

```json
{
  "bundleVersion": "0.1.0",
  "defaultBlueprintUrl": "./assets/blueprints/default.blueprint.json",
  "addonProxyPath": "/__addon_proxy__",
  "addonProxyUrl": "https://zip-proxy.erseco.workers.dev/",
  "siteTitle": "Omeka S Playground",
  "landingPath": "/admin",
  "locale": "en_US",
  "timezone": "UTC",
  "autologin": true,
  "resetOnVersionMismatch": true,
  "admin": {
    "username": "admin",
    "password": "password",
    "email": "admin@example.com"
  },
  "omekaVersion": "4.2.0",
  "runtimes": [
    { "id": "php81", "label": "PHP 8.1", "phpVersion": "8.1", "default": false },
    { "id": "php82", "label": "PHP 8.2", "phpVersion": "8.2", "default": false },
    { "id": "php83", "label": "PHP 8.3", "phpVersion": "8.3", "default": true },
    { "id": "php84", "label": "PHP 8.4", "phpVersion": "8.4", "default": false },
    { "id": "php85", "label": "PHP 8.5", "phpVersion": "8.5", "default": false }
  ]
}
```

--------------------------------

### Perform Syntax Checks (Node.js)

Source: https://github.com/ateeducacion/omeka-s-playground/blob/main/docs/development.md

Commands to perform targeted syntax checks on various JavaScript and PHP files within the Omeka-S Playground project using Node.js.

```javascript
node --check src/shell/main.js
node --check sw.js
node --check php-worker.js
node --check src/runtime/bootstrap.js
node --check src/runtime/vfs.js
```

--------------------------------

### Normalize User Roles in Blueprints

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

This JavaScript snippet demonstrates how user role aliases are mapped to canonical Omeka S roles. It shows how variations like 'admin', 'globaladmin', and 'global_admin' are treated as the same role, while standard roles pass through unchanged.

```javascript
const users = [
  { email: "admin@test.com", password: "pass", role: "admin" },
  { email: "admin@test.com", password: "pass", role: "global_admin" },
  { email: "admin@test.com", password: "pass", role: "globaladmin" },
  { email: "site@test.com", password: "pass", role: "supervisor" },
  { email: "site@test.com", password: "pass", role: "site_admin" },
  { email: "site@test.com", password: "pass", role: "siteadmin" },
  { email: "editor@test.com", password: "pass", role: "editor" },
  { email: "reviewer@test.com", password: "pass", role: "reviewer" },
  { email: "author@test.com", password: "pass", role: "author" },
  { email: "viewer@test.com", password: "pass", role: "researcher" }
];
```

--------------------------------

### Normalize Blueprint Input - JavaScript

Source: https://context7.com/ateeducacion/omeka-s-playground/llms.txt

The `normalizeBlueprint` function processes raw blueprint data, applying default values, validating user inputs, and standardizing addon sources. It takes raw blueprint data and a configuration object as input, returning a complete blueprint ready for use. Dependencies include the `normalizeBlueprint` and `buildDefaultBlueprint` functions from './src/shared/blueprint.js'.

```javascript
import { normalizeBlueprint, buildDefaultBlueprint } from './src/shared/blueprint.js';

// Configuration object (typically from playground.config.json)
const config = {
  siteTitle: "Omeka S Playground",
  locale: "en_US",
  timezone: "UTC",
  admin: {
    username: "admin",
    email: "admin@example.com",
    password: "password"
  },
  runtimes: [
    { id: "php83", label: "PHP 8.3", phpVersion: "8.3", default: true }
  ]
};

// Raw blueprint input (may be incomplete)
const rawBlueprint = {
  landingPage: "admin",  // Will be normalized to "/admin"
  users: [
    {
      email: "demo@example.com",
      password: "demo123",
      role: "admin"  // Will be normalized to "global_admin"
    }
  ],
  modules: [
    "CSVImport",  // String shorthand, will be expanded
    { name: "Mapping", state: "activate" }
  ]
};

// Normalize the blueprint
const normalized = normalizeBlueprint(rawBlueprint, config);
console.log(normalized);
// Output:
// {
//   "$schema": "https://ateeducacion.github.io/omeka-s-playground/assets/blueprints/blueprint-schema.json",
//   "meta": { "title": "Omeka S Playground Blueprint", ... },
//   "landingPage": "/admin",
//   "users": [{ username: "demo", email: "demo@example.com", role: "global_admin", ... }],
//   "modules": [
//     { name: "CSVImport", state: "activate", source: { type: "bundled" } },
//     { name: "Mapping", state: "activate", source: { type: "bundled" } }
//   ],
//   ...
// }

// Build a complete default blueprint
const defaultBlueprint = buildDefaultBlueprint(config);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.