Overview

Save and Load Preset Manager

Purpose

The SaveAndLoadPresetManager provides a versioned JSON transport contract for preset export/import flows.

It standardizes:

preset envelope structure (version, resource, metadata, payload)
file-level validation and parsing
transport version compatibility checks
deterministic file naming
deterministic user-facing error messages

What This Module Is

A transport-layer capability, not a feature module
A class-based static utility set for preset serialization/parsing
Schema-agnostic with respect to module form payloads
Safe-by-default with explicit guards for malformed files and incompatible resources

What This Module Is Not

This module is not:

A UI component
A React hook
A domain schema validator for modules
A migration engine for business entities

It does not decide whether a payload is valid for a specific module schema. The caller owns domain-level validation after transport parsing.

Transport Contract

All presets are persisted as JSON with this envelope:

{
  "version": 1,
  "resource": "monetization.offers",
  "metadata": {
    "exportedAt": "2026-05-25T18:10:54.410Z",
    "site": "dirtvision",
    "siteId": "e230bd58-b3b2-4cc1-8ba0-a17c9b875ef5",
    "workflow": "offer-create",
    "appVersion": "v5"
  },
  "payload": {}
}

Public Surface

Area	Symbol	Role
Serializer	`PresetSerializer.buildPresetFile(payload, options)`	Builds transport envelope for export
Serializer	`PresetSerializer.serializePreset(preset)`	Converts envelope to JSON string
Serializer	`PresetSerializer.buildPresetFileName(args)`	Generates deterministic filename (with optional preset-name prefix)
Parser	`PresetParser.parsePresetText(serializedPreset, expectedResource?)`	Parses and validates transport from text
Parser	`PresetParser.parsePresetFile(file, expectedResource?)`	Parses and validates transport from uploaded file
Migration	`PresetMigration.migrate(preset)`	Enforces transport-version compatibility
Validator	`PresetValidator.assertPayloadObject(payload)`	Validates export payload as JSON object
Validator	`PresetValidator.assertValidPresetTransport(raw)`	Validates import envelope shape
Validator	`PresetValidator.validatePresetUploadFile(file)`	Validates file extension/MIME before parsing
Error mapping	`getPresetUserMessage(error)`	Converts transport errors to deterministic user-facing messages

Key Constants

Constant	Value	Purpose
`PRESET_TRANSPORT_VERSION`	`1`	Current transport contract version
`PRESET_DOWNLOAD_MIME_TYPE`	`application/json;charset=utf-8;`	Download blob MIME type
`PRESET_ALLOWED_MIME_TYPES`	`application/json`, `text/json`	Allowed MIME types for upload validation

Module Map

File	Responsibility
`types.ts`	Transport contract and helper argument/result types
`constants.ts`	Version and MIME constants
`errors.ts`	Typed error taxonomy and user-message adapter
`validators.ts`	Envelope/payload/file validation guards
`migration.ts`	Transport version gate (`migrate`)
`parser.ts`	File/text parsing pipeline with compatibility check
`serializer.ts`	Envelope builder, JSON serializer, deterministic filename generation