@memizy/oqse 0.1.1 → 0.1.3

package/dist/src/header.d.ts

@@ -0,0 +1,7 @@
+import { OQSEMeta } from './oqse';
+type OQSEHeaderMetaProjection = Pick<OQSEMeta, 'id' | 'title' | 'language' | 'updatedAt' | 'description' | 'author' | 'subject' | 'tags' | 'createdAt' | 'estimatedTime' | 'requirements'>;
+export type OQSEHeader = Omit<OQSEHeaderMetaProjection, 'createdAt'> & Partial<Pick<OQSEHeaderMetaProjection, 'createdAt'>> & {
+    url: string;
+    $schema?: string;
+};
+export {};

package/dist/src/headerValidation.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { OQSEHeader } from './header';
+export declare const OQSEHeaderSchema: z.ZodType<OQSEHeader>;
+export declare function validateOQSEHeader(data: unknown): OQSEHeader;
+export declare function safeValidateOQSEHeader(data: unknown): ReturnType<typeof OQSEHeaderSchema.safeParse>;

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

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

package/dist/src/index.d.ts

@@ -4,4 +4,7 @@ export * from './manifest';
 export * from './manifestValidation';
 export * from './progress';
 export * from './progressValidation';
+export * from './header';
+export * from './headerValidation';
 export * from './utils';
+export * from './richTextProcessor';

package/dist/src/manifest.d.ts

@@ -1,4 +1,4 @@
-import { FeatureProfile } from './oqse';
+import { FeatureProfile, PersonObject } from './oqse';
 export type { FeatureProfile } from './oqse';
 /**
  * Official actions from the OQSE Action Registry (Section 2.1.3).
@@ -9,7 +9,8 @@ export type { FeatureProfile } from './oqse';
  * - `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';
+export declare const OFFICIAL_ACTIONS: readonly ["render", "edit", "validate", "import", "export"];
+export type OfficialAction = typeof OFFICIAL_ACTIONS[number];
 /**
  * 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.
@@ -47,11 +48,12 @@ export type OQSEQuestionDensity = 'low' | 'medium' | 'high';
  * `meta.requirements.features` (Study Set) to signal support/requirement.
  *
  * Dependency notes:
- * - `syntax-highlighting`, `mermaid`, `smiles`, `abc-notation`, `html-safe`
+ * - `syntax-highlighting`, `mermaid`, `smiles`, `abc-notation`, `html`
  *   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';
+export declare const OFFICIAL_FEATURE_KEYS: readonly ["markdown", "math", "rtl", "html", "syntax-highlighting", "mermaid", "smiles", "abc-notation", "text-to-speech", "voice-input", "handwriting-recognition"];
+export type OfficialFeatureKey = typeof OFFICIAL_FEATURE_KEYS[number];
 /**
  * A custom feature using the required `x-` prefix (e.g., `"x-memizy-3d-voxel"`).
  * MUST NOT collide with current or future official registry entries.
@@ -68,7 +70,8 @@ export type FeatureFlag = OfficialFeatureKey | CustomFeatureKey;
  * 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';
+export declare const OFFICIAL_ITEM_PROPERTIES: readonly ["hints", "explanation", "incorrectFeedback", "sources", "relatedItems", "dependencyItems", "timeLimit", "lang", "topic", "pedagogy"];
+export type OfficialItemProperty = typeof OFFICIAL_ITEM_PROPERTIES[number];
 /**
  * A custom item property using the `x-` prefix.
  */
@@ -83,7 +86,8 @@ export type ItemPropertyKey = OfficialItemProperty | CustomItemProperty;
  * 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';
+export declare const OFFICIAL_META_PROPERTIES: readonly ["description", "thumbnail", "subject", "language", "author", "contributors", "license", "ageRestriction", "tags", "tagDefinitions", "sourceMaterials", "estimatedTime", "prerequisites", "translations", "relatedSets"];
+export type OfficialMetaProperty = typeof OFFICIAL_META_PROPERTIES[number];
 /**
  * A custom meta property using the `x-` prefix.
  */
@@ -160,7 +164,7 @@ export interface ManifestAssets {
  * 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
+ * @see ../oqse-manifest.md#capabilities-object-extends-featureprofile
  */
 export interface ManifestCapabilities extends FeatureProfile {
     /**
@@ -231,12 +235,12 @@ export interface ManifestCapabilities extends FeatureProfile {
  * - 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
+ * @see ../oqse-manifest.md#oqsem-application-manifest
  *
  * @example
  * ```json
  * {
- *   "$schema": "https://memizy.com/schemas/oqse-manifest/v0.1.json",
+ *   "$schema": "https://cdn.jsdelivr.net/gh/memizy/oqse-specification@main/schemas/oqse-manifest-v0.1.json",
  *   "version": "0.1",
  *   "pluginVersion": "2.1.0",
  *   "id": "https://memizy.com/universal-player",
@@ -253,7 +257,7 @@ 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"`
+    * @example `"https://cdn.jsdelivr.net/gh/memizy/oqse-specification@main/schemas/oqse-manifest-v0.1.json"`
      */
     $schema?: string;
     /**
@@ -305,23 +309,22 @@ export interface OQSEManifest {
     /**
      * Human-readable description of what the application does.
      * Displayed in host environments and plugin catalogs.
-    * **Plain Text** - no Markdown or HTML.
+    * **Rich Content** (Markdown/LaTeX supported by host capabilities).
      */
     description?: string;
     /**
-     * Name of the author or organization.
-     * **Plain Text.**
-     *
-     * @example `"Memizy Team"`
+     * Information about the main author or organization.
+     * Uses the standard `PersonObject` structure.
      */
-    author?: string;
+    author?: PersonObject;
     /**
-     * URL of the author or organization.
-     * MUST be an absolute URL.
-     *
-     * @example `"https://memizy.com"`
+     * Array of information about other contributors.
      */
-    authorUrl?: string;
+    contributors?: PersonObject[];
+    /** SPDX license identifier (e.g., "MIT", "GPL-3.0"). */
+    license?: string;
+    /** URI to the full text of the license. */
+    licenseUrl?: string;
     /**
      * BCP 47 locale codes for the application's supported UI languages.
      * If absent or `[]`, the host SHOULD assume the application supports English.

package/dist/src/manifestValidation.d.ts

@@ -64,16 +64,16 @@ export declare const ManifestCapabilitiesSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
- * Full OQSE Application Manifest schema (T�2.1.1).
+ * Full OQSE Application Manifest schema (Table 2.1.1).
  *
  * Validated constraints beyond syntax:
- * - `minOqseVersion` �� `maxOqseVersion` when both are present
+ * - `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;
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
     appName: z.ZodString;
     version: z.ZodString;
     pluginVersion: z.ZodOptional<z.ZodString>;
@@ -93,8 +93,20 @@ export declare const OQSEManifestSchema: z.ZodObject<{
             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>;
+    author: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    contributors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    license: z.ZodOptional<z.ZodString>;
+    licenseUrl: z.ZodOptional<z.ZodString>;
     locales: z.ZodOptional<z.ZodArray<z.ZodString>>;
     description: z.ZodOptional<z.ZodString>;
     emoji: z.ZodOptional<z.ZodString>;
@@ -151,15 +163,16 @@ export declare function safeValidateManifest(data: unknown): ReturnType<typeof O
  * @example
  * ```ts
  * console.error(formatManifestErrors(result.error));
- * // ��� "id: ID mus+� b+�t ve tvaru reverse-domain..."
- * // ��� "capabilities.actions: Aplikace mus+� podporovat alespo+� jednu akci"
+ * // Example output:
+ * // "id: ID must be an absolute URL or a URN-format UUID (urn:uuid:...)"
+ * // "capabilities.actions: Application must support at least one action"
  * ```
  */
 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.
+ * This is a fast pre-check - use `validateManifest` for full validation.
  *
  * @param data - Any value.
  * @returns `true` if `data` has the minimum required shape.

package/dist/src/oqse.d.ts

@@ -5,7 +5,7 @@
  * Type-safe TypeScript definitions for the OQSE specification.
  * Uses Discriminated Unions to make invalid states unrepresentable.
  *
- * @see /SPECIFICATION.md
+ * @see ../oqse.md
  */
 /**
  * BCP 47 language code (e.g., "en", "en-US", "cs", "zh-Hans")
@@ -178,7 +178,7 @@ export type TagDefinitionDictionary = Record<string, TagDefinition>;
  * It declares which features, LaTeX packages, and item/meta properties
  * an application supports (in Manifest) or requires (in Study Set).
  *
- * @see /SPECIFICATION.md#22-feature-profile--official-registry
+ * @see ../oqse.md#feature-profile--official-registry
  */
 export interface FeatureProfile {
     /**
@@ -203,29 +203,6 @@ export interface FeatureProfile {
      */
     metaProperties?: string[];
 }
-/**
- * Feature requirement type
- * @deprecated Use FeatureProfile instead for spec-compliant requirements.
- */
-export type FeatureType = 'official' | 'experimental' | 'proprietary';
-/**
- * Official feature names
- */
-export type OfficialFeatureName = 'math' | 'media-image' | 'media-audio' | 'media-video' | 'hotspots' | 'complex-pairing' | 'open-text';
-/**
- * Feature requirement object
- */
-export interface FeatureRequirement {
-    /** Feature name */
-    name: string;
-    /** Feature type */
-    type: FeatureType;
-    /**
-     * For proprietary features: Domain name of the provider (e.g., "memizy.com").
-     * MUST be present for type: "proprietary", ignored for other types.
-     */
-    vendor?: string;
-}
 /**
  * Translation object defining reference to translated version of this set
  */
@@ -279,31 +256,12 @@ export interface Pedagogy {
     /** Penalty for each wrong choice (0.0 - 1.0) */
     penaltyPerWrong?: number;
 }
-/**
- * Math renderer type
- */
-export type MathRenderer = 'katex' | 'mathjax';
-/**
- * Math settings for rendering mathematical formulas
- */
-export interface MathSettings {
-    /** Preferred renderer */
-    renderer?: MathRenderer;
-    /** Array of LaTeX package names required for proper formula display */
-    packages?: string[];
-}
 /**
  * Metadata describing the entire set
  */
 export interface OQSEMeta {
     /** Unique UUID of the set */
     id: string;
-    /**
-     * Origin UUID of the creator.
-     * Used to verify ownership when syncing between devices or cloud.
-     * If created anonymously, this is the local device install ID.
-     */
-    originUid?: string;
     /** Language code of the set (BCP 47) */
     language: LanguageCode;
     /** Title of the study set (Plain Text) */
@@ -340,11 +298,6 @@ export interface OQSEMeta {
      * @see FeatureProfile
      */
     requirements?: FeatureProfile;
-    /**
-     * @deprecated Use `requirements` (FeatureProfile) instead.
-     * This field used a non-spec-compliant structure.
-     */
-    requiredFeatures?: FeatureRequirement[];
     /** Array of text labels (tags) for the entire set */
     tags?: string[];
     /** Dictionary of tag definitions */
@@ -359,8 +312,6 @@ export interface OQSEMeta {
     prerequisites?: LinkedSetObject[];
     /** Array of references to related OQSE sets */
     relatedSets?: LinkedSetObject[];
-    /** Configuration for rendering mathematical formulas */
-    mathSettings?: MathSettings;
     /** Object for metadata determined by the author/creator */
     customData?: Record<string, unknown>;
     /** Object for metadata specific to a particular software application */
@@ -380,6 +331,8 @@ export interface BaseItem {
     lang?: LanguageCode;
     /** Array of text labels (tags) for this item */
     tags?: string[];
+    /** Primary category, chapter, or lecture name for this item */
+    topic?: string;
     /** Numeric difficulty from 1 (easy) to 5 (hard) */
     difficulty?: number;
     /** Recommended time limit in seconds for answering this item */
@@ -487,6 +440,10 @@ export interface MeshHotspot extends BaseHotspot {
  * Use `MeshHotspot` for 3D model mesh selection.
  */
 export type HotspotObject = RectHotspot | CircleHotspot | PolygonHotspot | MeshHotspot;
+/**
+ * 2D hotspots for image-based interactions.
+ */
+export type Hotspot2D = RectHotspot | CircleHotspot | PolygonHotspot;
 /**
  * A 3D point or vector with X, Y, Z coordinates.
  * Used for camera setup in `pin-on-model` items.
@@ -586,6 +543,8 @@ export interface NoteItem extends BaseItem {
     title?: string;
     /** Main educational content (Rich Content) */
     content: string;
+    /** Additional content that is initially hidden (Rich Content) */
+    hiddenContent?: string;
 }
 /**
  * Flashcard item
@@ -790,7 +749,7 @@ export interface PinOnImageItem extends BaseItem {
     /** Key from assets, which determines the image to be clicked on */
     targetAsset: string;
     /** Array defining correct areas. Min 1 hotspot. */
-    hotspots: HotspotObject[];
+    hotspots: Hotspot2D[];
     /** Whether user must mark more than one hotspot. Default: false */
     multipleCorrect?: boolean;
     /**