@memizy/oqse 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from './oqse';
+export * from './oqseValidation';
+export * from './manifest';
+export * from './manifestValidation';
+export * from './progress';
+export * from './progressValidation';
+export * from './utils';

package/dist/src/manifest.d.ts

@@ -0,0 +1,429 @@
+import { FeatureProfile } from './oqse';
+export type { FeatureProfile } from './oqse';
+/**
+ * Official actions from the OQSE Action Registry (Section 2.1.3).
+ *
+ * - `render`   - Player/learning mode: displays items interactively.
+ * - `edit`     - Authoring mode: creates/modifies item content.
+ * - `validate` - Verification mode: checks structural/logical correctness.
+ * - `import`   - Data ingestion: parses OQSE data into an internal system.
+ * - `export`   - Data generation: serializes internal data into OQSE format.
+ */
+export type OfficialAction = 'render' | 'edit' | 'validate' | 'import' | 'export';
+/**
+ * Custom action using the required `x-` prefix (e.g., `"x-preview"`, `"x-sync"`).
+ * Host environments that do not recognize a custom action MUST ignore it.
+ */
+export type CustomAction = `x-${string}`;
+/**
+ * Any action value: official from the Action Registry or a custom `x-` prefixed action.
+ */
+export type OQSEAction = OfficialAction | CustomAction;
+/**
+ * Primary experience type of an application.
+ *
+ * - `"game"`  - Entertainment-first; gameplay mechanics take priority.
+ * - `"fun"`   - Balanced blend of interactivity and learning.
+ * - `"drill"` - Maximally focused, distraction-free repetition.
+ *
+ * If absent, no assumption is made.
+ */
+export type OQSEStudyMode = 'game' | 'fun' | 'drill';
+/**
+ * Ratio of quiz items relative to non-question game elements.
+ *
+ * - `"low"`    - Questions appear rarely; gameplay dominates.
+ * - `"medium"` - Questions and gameplay are roughly balanced.
+ * - `"high"`   - Nearly every interaction is a question.
+ *
+ * If `studyMode` is `"drill"`, hosts SHOULD treat this as `"high"` regardless.
+ * If absent, no assumption is made.
+ */
+export type OQSEQuestionDensity = 'low' | 'medium' | 'high';
+/**
+ * All officially recognized feature keys from the OQSE Feature Registry (Section 2.2).
+ *
+ * Features are declared in `capabilities.features` (Manifest) and in
+ * `meta.requirements.features` (Study Set) to signal support/requirement.
+ *
+ * Dependency notes:
+ * - `syntax-highlighting`, `mermaid`, `smiles`, `abc-notation`, `html-safe`
+ *   are only meaningful when `markdown` is also declared.
+ * - `latexPackages` (in FeatureProfile) is only meaningful when `math` is declared.
+ */
+export type OfficialFeatureKey = 'markdown' | 'html-safe' | 'math' | 'ruby-annotations' | 'rtl' | 'syntax-highlighting' | 'mermaid' | 'smiles' | 'abc-notation' | 'text-to-speech' | 'voice-input' | 'handwriting-recognition';
+/**
+ * A custom feature using the required `x-` prefix (e.g., `"x-memizy-3d-voxel"`).
+ * MUST NOT collide with current or future official registry entries.
+ * SHOULD be documented in the manifest's own `appSpecific` field.
+ */
+export type CustomFeatureKey = `x-${string}`;
+/**
+ * Any feature flag: official from the registry or a custom `x-` prefixed value.
+ */
+export type FeatureFlag = OfficialFeatureKey | CustomFeatureKey;
+/**
+ * Official item-level property keys from the OQSE itemProperties registry (Section 2.2).
+ *
+ * Declared in `capabilities.itemProperties` (app support) and
+ * `meta.requirements.itemProperties` (set requirement).
+ */
+export type OfficialItemProperty = 'hints' | 'explanation' | 'incorrectFeedback' | 'sources' | 'relatedItems' | 'dependencyItems' | 'timeLimit' | 'lang' | 'topic' | 'pedagogy';
+/**
+ * A custom item property using the `x-` prefix.
+ */
+export type CustomItemProperty = `x-${string}`;
+/**
+ * Any item property key: official or custom.
+ */
+export type ItemPropertyKey = OfficialItemProperty | CustomItemProperty;
+/**
+ * Official set-level (meta) property keys from the OQSE metaProperties registry (Section 2.2).
+ *
+ * Declared in `capabilities.metaProperties` (app support) and
+ * `meta.requirements.metaProperties` (set requirement).
+ */
+export type OfficialMetaProperty = 'description' | 'thumbnail' | 'subject' | 'language' | 'author' | 'contributors' | 'license' | 'ageRestriction' | 'tags' | 'tagDefinitions' | 'sourceMaterials' | 'estimatedTime' | 'prerequisites' | 'translations' | 'relatedSets';
+/**
+ * A custom meta property using the `x-` prefix.
+ */
+export type CustomMetaProperty = `x-${string}`;
+/**
+ * Any meta property key: official or custom.
+ */
+export type MetaPropertyKey = OfficialMetaProperty | CustomMetaProperty;
+/**
+ * A typed "explicit list" array - lists concrete accepted values.
+ * Used for MIME type arrays in ManifestAssets and for item `types`.
+ */
+export type ExplicitArray<T extends string> = T[];
+/**
+ * A "wildcard" array - the single-element tuple `["*"]` meaning "all accepted."
+ */
+export type WildcardArray = ['*'];
+/**
+ * The full wildcard-or-explicit-or-null semantic for `types` and `assets` values:
+ *
+ * | Value            | Meaning                              |
+ * |------------------|--------------------------------------|
+ * | `["*"]`          | All accepted (any type/MIME).        |
+ * | `["a/b", ...]`   | Only the listed values are supported.|
+ * | `null`           | Not supported; hosts MUST NOT pass.  |
+ * | `[]` / absent    | Equivalent to `null` (not supported).|
+ *
+ * Parsers MUST treat `[]` identically to `null`.
+ */
+export type WildcardOrExplicit<T extends string> = WildcardArray | ExplicitArray<T> | null;
+/**
+ * Common image MIME types recognized by OQSE.
+ * Applications MAY support additional types; these are well-known values.
+ */
+export type ImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'image/svg+xml' | 'image/avif' | 'image/bmp' | `image/${string}`;
+/**
+ * Common audio MIME types recognized by OQSE.
+ */
+export type AudioMimeType = 'audio/mpeg' | 'audio/ogg' | 'audio/wav' | 'audio/aac' | 'audio/flac' | 'audio/mp4' | `audio/${string}`;
+/**
+ * Common video MIME types recognized by OQSE.
+ */
+export type VideoMimeType = 'video/mp4' | 'video/webm' | 'video/ogg' | 'video/quicktime' | `video/${string}`;
+/**
+ * 3D model MIME types recognized by OQSE.
+ * glTF format (`.glb` / `.gltf`) is RECOMMENDED as the universal baseline.
+ */
+export type ModelMimeType = 'model/gltf-binary' | 'model/gltf+json' | 'model/obj' | 'model/fbx' | `model/${string}`;
+/**
+ * Asset support map for the four supported asset categories.
+ *
+ * Per each category:
+ * - `["*"]`             - Accepts any MIME type in this category.
+ * - `["image/png", ...]` - Only the listed MIME types.
+ * - `null` or absent    - Category not supported.
+ * - `[]`                - Equivalent to `null` (not supported); SHOULD NOT be emitted.
+ *
+ * If the entire `assets` object is omitted, the application declares no media support.
+ */
+export interface ManifestAssets {
+    /** Image asset support */
+    image?: WildcardOrExplicit<ImageMimeType>;
+    /** Audio asset support */
+    audio?: WildcardOrExplicit<AudioMimeType>;
+    /** Video asset support */
+    video?: WildcardOrExplicit<VideoMimeType>;
+    /** 3D model asset support. glTF (`model/gltf-binary`) is RECOMMENDED. */
+    model?: WildcardOrExplicit<ModelMimeType>;
+}
+/**
+ * The `capabilities` object in the Application Manifest.
+ *
+ * Extends FeatureProfile by adding `actions`, `types`, and `assets`.
+ * Declares everything the application can do, what types it handles,
+ * what media formats it accepts, and which OQSE features it supports.
+ *
+ * @see /SPECIFICATION.md#212-capabilities-object-extends-featureprofile
+ */
+export interface ManifestCapabilities extends FeatureProfile {
+    /**
+    * Actions the application can perform (REQUIRED, >=1 value).
+     * MUST contain at least one value from the Action Registry.
+     * Custom actions MUST use the `x-` prefix.
+     *
+     * @example `["render", "edit"]`
+     */
+    actions: OQSEAction[];
+    /**
+     * OQSE item types the application supports.
+     *
+     * - Required (at least one type or `["*"]`) when `actions` includes `render` or `edit`.
+     * - MAY be omitted for `validate`, `import`, or `export`-only applications.
+     * - `["*"]` - supports all item types.
+     * - `[]` / `null` - equivalent; treated as "no types declared".
+     * - Custom types MUST use the `x-` prefix.
+     *
+     * @example `["flashcard", "mcq-single", "*"]`
+     */
+    types?: WildcardOrExplicit<string>;
+    /**
+     * Media asset support map.
+     * If omitted entirely, the application declares no media support.
+     *
+     * @see ManifestAssets
+     */
+    assets?: ManifestAssets;
+    /**
+     * Array of supported feature flags.
+     * Values MUST come from the Official Feature Registry or use the `x-` prefix.
+     *
+     * @see OfficialFeatureKey
+     * @see FeatureFlag
+     */
+    features?: FeatureFlag[];
+    /**
+     * Array of supported LaTeX packages.
+     * Only meaningful when `features` includes `"math"`.
+     *
+     * @example `["mhchem", "amsmath"]`
+     */
+    latexPackages?: string[];
+    /**
+     * Item-level properties the application supports.
+     *
+     * @see OfficialItemProperty
+     * @see ItemPropertyKey
+     */
+    itemProperties?: ItemPropertyKey[];
+    /**
+     * Set-level metadata properties the application supports.
+     *
+     * @see OfficialMetaProperty
+     * @see MetaPropertyKey
+     */
+    metaProperties?: MetaPropertyKey[];
+}
+/**
+ * OQSE Application Manifest (Section 2.1).
+ *
+ * Every application, micro-frontend, or plugin that interacts with OQSE data
+ * MUST declare its capabilities using this structure.
+ *
+ * **Delivery options:**
+ * - HTML application: `<script type="application/oqse-manifest+json">` tag.
+ * - Non-HTML application: static `oqse-manifest.json` at the deployment root.
+ * - HTTP discovery: `Link: <manifest.json>; rel="oqse-manifest"` header.
+ *
+ * @see /SPECIFICATION.md#21-the-application-manifest
+ *
+ * @example
+ * ```json
+ * {
+ *   "$schema": "https://memizy.com/schemas/oqse-manifest/v0.1.json",
+ *   "version": "0.1",
+ *   "pluginVersion": "2.1.0",
+ *   "id": "https://memizy.com/universal-player",
+ *   "appName": "Memizy Universal Player",
+ *   "capabilities": {
+ *     "actions": ["render"],
+ *     "types": ["flashcard", "mcq-single"],
+ *     "features": ["math", "markdown"]
+ *   }
+ * }
+ * ```
+ */
+export interface OQSEManifest {
+    /**
+     * URL reference to the JSON Schema for automatic validation.
+     * Recommended but not required.
+     * @example `"https://memizy.com/schemas/oqse-manifest/v0.1.json"`
+     */
+    $schema?: string;
+    /**
+     * Version of the Application Manifest format (REQUIRED).
+     * MUST follow `"MAJOR.MINOR"` format. The current version is `"0.1"`.
+     * Malformed values MUST cause the host to reject this manifest.
+     *
+     * @example `"0.1"`
+     */
+    version: string;
+    /**
+     * Version of the application/plugin itself using SemVer.
+     * Independent of the manifest format version.
+     *
+     * @example `"2.1.0"`
+     */
+    pluginVersion?: string;
+    /**
+     * Minimum OQSE spec version this application requires.
+     * MUST follow `"MAJOR.MINOR"` format. Version comparison is numeric field-by-field.
+     * If malformed, treat as absent and SHOULD warn.
+     * MUST be \u2264 `maxOqseVersion` when both are declared.
+     *
+     * @example `"0.1"`
+     */
+    minOqseVersion?: string;
+    /**
+     * Maximum OQSE spec version this application is compatible with.
+     * MUST follow `"MAJOR.MINOR"` format. If absent, no upper bound is assumed.
+     * If malformed, treat as absent and SHOULD warn.
+     *
+     * @example `"1.99"`
+     */
+    maxOqseVersion?: string;
+    /**
+     * Unique identifier for this application (REQUIRED).
+     * MUST be either:
+     * - A controlled URL (preferred): `"https://memizy.com/player"`
+     * - A URN-format UUID: `"urn:uuid:019aa600-abc1-7234-b678-c0ffee000001"`
+     */
+    id: string;
+    /**
+     * Human-readable name of the application (REQUIRED).
+     * MUST be non-empty. Plain Text.
+     *
+     * @example `"Memizy Universal Player"`
+     */
+    appName: string;
+    /**
+     * Human-readable description of what the application does.
+     * Displayed in host environments and plugin catalogs.
+    * **Plain Text** - no Markdown or HTML.
+     */
+    description?: string;
+    /**
+     * Name of the author or organization.
+     * **Plain Text.**
+     *
+     * @example `"Memizy Team"`
+     */
+    author?: string;
+    /**
+     * URL of the author or organization.
+     * MUST be an absolute URL.
+     *
+     * @example `"https://memizy.com"`
+     */
+    authorUrl?: string;
+    /**
+     * BCP 47 locale codes for the application's supported UI languages.
+     * If absent or `[]`, the host SHOULD assume the application supports English.
+     *
+     * @example `["en", "cs"]`
+     */
+    locales?: string[];
+    /**
+     * Plain-text keywords for filtering and discovery in host environments/catalogs.
+     * Uses the same convention as `meta.tags` in study sets.
+     *
+     * @example `["flashcards", "spaced-repetition", "chess"]`
+     */
+    tags?: string[];
+    /**
+     * A single emoji used as the application's visual identity in catalogs.
+     * SHOULD be a single visually-rendered emoji glyph.
+     * Multi-codepoint emoji (flags, family sequences) are acceptable.
+     * If a future `iconUrl` field is also declared, hosts SHOULD prefer that.
+     *
+     * @example `"\uD83E\uDDE0"` (brain), `"\uD83D\uDE80"` (rocket), `"\uD83C\uDFAE"` (game controller)
+     */
+    emoji?: string;
+    /**
+     * Primary experience type of the application.
+     * MUST be one of `"game"`, `"fun"`, or `"drill"`.
+     * If absent, no assumption is made.
+     */
+    studyMode?: OQSEStudyMode;
+    /**
+     * Ratio of quiz questions relative to other game elements.
+     * MUST be one of `"low"`, `"medium"`, or `"high"`.
+     * If `studyMode` is `"drill"`, hosts SHOULD treat this as `"high"`.
+     * If absent, no assumption is made.
+     */
+    questionDensity?: OQSEQuestionDensity;
+    /**
+     * Object for application-specific metadata not covered by standard fields.
+     * Applications declaring custom `x-` features SHOULD document their semantics here.
+     * Other applications MUST ignore this object.
+     */
+    appSpecific?: Record<string, unknown>;
+    /**
+     * Capabilities of this application (REQUIRED).
+     * Extends FeatureProfile with `actions`, `types`, and `assets`.
+     *
+     * @see ManifestCapabilities
+     */
+    capabilities: ManifestCapabilities;
+}
+/**
+ * Validates that a version string follows the `"MAJOR.MINOR"` format
+ * required by both `manifest.version` and `minOqseVersion`/`maxOqseVersion`.
+ *
+ * @param version - The version string to validate.
+ * @returns `true` if valid (e.g., `"0.1"`, `"2.10"`), `false` otherwise.
+ *
+ * @example
+ * isValidManifestVersion("0.1")   // true
+ * isValidManifestVersion("2.10")  // true
+ * isValidManifestVersion("1.0.0") // false (SemVer, not allowed here)
+ * isValidManifestVersion("v0.1")  // false
+ */
+export declare function isValidManifestVersion(version: string): boolean;
+/**
+ * Validates that a SemVer string follows the `"MAJOR.MINOR.PATCH"` format
+ * required by `manifest.pluginVersion`.
+ *
+ * @param version - The SemVer string to validate.
+ * @returns `true` if valid (e.g., `"2.1.0"`, `"1.0.0-rc.1"`), `false` otherwise.
+ */
+export declare function isValidSemVer(version: string): boolean;
+/**
+ * Numerically compares two `"MAJOR.MINOR"` version strings.
+ *
+ * @returns
+ * - Negative number if `a < b`
+ * - `0` if `a === b`
+ * - Positive number if `a > b`
+ *
+ * @example
+ * compareManifestVersions("0.1", "1.10")  // negative (0.1 < 1.10)
+ * compareManifestVersions("2.0", "1.99")  // positive (2.0 > 1.99)
+ */
+export declare function compareManifestVersions(a: string, b: string): number;
+/**
+ * Type guard: checks whether a value is a valid `OQSEManifest` at runtime.
+ *
+ * Performs only structural validation (presence of required fields and correct types).
+ * For full spec-compliant validation including enum values and version format,
+ * use the Zod schema in `src/app/schemas/`.
+ *
+ * @param value - Unknown parsed JSON value.
+ * @returns `true` if the value has the required shape of an `OQSEManifest`.
+ */
+export declare function isOQSEManifest(value: unknown): value is OQSEManifest;
+/**
+ * Checks whether an OQSE file's version is within the application's
+ * declared min/max OQSE version range.
+ *
+ * @param fileVersion   - The `version` field of the OQSE study set file (e.g., `"0.1"`).
+ * @param manifest      - The Application Manifest to check against.
+ * @returns `true` if the file is compatible, `false` if the host MUST NOT load it.
+ */
+export declare function isVersionCompatible(fileVersion: string, manifest: OQSEManifest): boolean;

package/dist/src/manifestValidation.d.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import { OQSEManifest } from './manifest';
+/**
+ * A valid OQSE action: one of the five official actions, or a vendor-specific
+ * action prefixed with `x-` (e.g. `x-acme-grade`).
+ */
+export declare const OQSEActionSchema: z.ZodString;
+/** Recommended study modality for a set of items. */
+export declare const OQSEStudyModeSchema: z.ZodEnum<{
+    game: "game";
+    fun: "fun";
+    drill: "drill";
+}>;
+/** Recommended question density per session. */
+export declare const OQSEQuestionDensitySchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>;
+/**
+ * A feature flag: one of the official keys or a vendor-specific key prefixed
+ * with `x-` (e.g. `x-acme-chemistry`).
+ */
+export declare const FeatureFlagSchema: z.ZodString;
+/** Official item-level extension property keys (or vendor-prefixed). */
+export declare const ItemPropertyKeySchema: z.ZodString;
+/** Official meta-level extension property keys (or vendor-prefixed). */
+export declare const MetaPropertyKeySchema: z.ZodString;
+/** Any valid image MIME type. */
+export declare const ImageMimeTypeSchema: z.ZodString;
+/** Any valid audio MIME type. */
+export declare const AudioMimeTypeSchema: z.ZodString;
+/** Any valid video MIME type. */
+export declare const VideoMimeTypeSchema: z.ZodString;
+/** Any valid 3D model MIME type. */
+export declare const ModelMimeTypeSchema: z.ZodString;
+/**
+ * Declares which media asset MIME types an application can handle.
+ * `null` means the category is not supported; `['*']` means all MIME types
+ * within that category are accepted; an array lists explicit MIME types.
+ */
+export declare const ManifestAssetsSchema: z.ZodObject<{
+    image: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    audio: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    video: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+}, z.core.$strip>;
+/**
+ * Full capability declaration of an OQSE-compatible application.
+ * Extends FeatureProfile with application-level capability fields.
+ */
+export declare const ManifestCapabilitiesSchema: z.ZodObject<{
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    latexPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    itemProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metaProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    actions: z.ZodArray<z.ZodString>;
+    types: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    assets: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+        audio: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+        video: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+        model: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Full OQSE Application Manifest schema (T�2.1.1).
+ *
+ * Validated constraints beyond syntax:
+ * - `minOqseVersion` �� `maxOqseVersion` when both are present
+ * - `version` adheres to MAJOR.MINOR format
+ * - `capabilities.actions` is non-empty (enforced by inner schema)
+ */
+export declare const OQSEManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    appName: z.ZodString;
+    version: z.ZodString;
+    pluginVersion: z.ZodOptional<z.ZodString>;
+    minOqseVersion: z.ZodOptional<z.ZodString>;
+    maxOqseVersion: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodObject<{
+        features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        latexPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        itemProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metaProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        actions: z.ZodArray<z.ZodString>;
+        types: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+        assets: z.ZodOptional<z.ZodObject<{
+            image: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            audio: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            video: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            model: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<"*">], z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null>, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    author: z.ZodOptional<z.ZodString>;
+    authorUrl: z.ZodOptional<z.ZodString>;
+    locales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    emoji: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    studyMode: z.ZodOptional<z.ZodEnum<{
+        game: "game";
+        fun: "fun";
+        drill: "drill";
+    }>>;
+    questionDensity: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    appSpecific: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Validates an unknown value against `OQSEManifestSchema`.
+ *
+ * @param data - The value to validate (typically parsed JSON).
+ * @returns The validated `OQSEManifest` object.
+ * @throws {z.ZodError} when validation fails.
+ *
+ * @example
+ * ```ts
+ * const manifest = validateManifest(JSON.parse(rawJson));
+ * manifest.capabilities.actions; // string[]
+ * ```
+ */
+export declare function validateManifest(data: unknown): OQSEManifest;
+/**
+ * Safely validates an unknown value without throwing.
+ *
+ * @param data - The value to validate.
+ * @returns A Zod `SafeParseReturnType` with `success` flag and either `data` or `error`.
+ *
+ * @example
+ * ```ts
+ * const result = safeValidateManifest(raw);
+ * if (result.success) {
+ *   console.log(result.data.id);
+ * } else {
+ *   console.error(formatManifestErrors(result.error));
+ * }
+ * ```
+ */
+export declare function safeValidateManifest(data: unknown): ReturnType<typeof OQSEManifestSchema.safeParse>;
+/**
+ * Formats a `ZodError` from manifest validation into a human-readable string.
+ *
+ * @param error - A `ZodError` returned by `safeValidateManifest`.
+ * @returns A newline-separated string listing each validation issue with its path.
+ *
+ * @example
+ * ```ts
+ * console.error(formatManifestErrors(result.error));
+ * // ��� "id: ID mus+� b+�t ve tvaru reverse-domain..."
+ * // ��� "capabilities.actions: Aplikace mus+� podporovat alespo+� jednu akci"
+ * ```
+ */
+export declare function formatManifestErrors(error: z.ZodError): string;
+/**
+ * Checks whether a plain object looks like an OQSE Manifest (duck-typing).
+ *
+ * This is a fast pre-check ��� use `validateManifest` for full validation.
+ *
+ * @param data - Any value.
+ * @returns `true` if `data` has the minimum required shape.
+ */
+export declare function isValidOQSEManifest(data: unknown): data is OQSEManifest;

package/dist/src/manifestValidation.test.d.ts

@@ -0,0 +1 @@
+export {};