@memizy/oqse 0.1.0 → 0.1.2

package/dist/src/index.d.ts

@@ -5,3 +5,4 @@ export * from './manifestValidation';
 export * from './progress';
 export * from './progressValidation';
 export * from './utils';
+export * from './richTextProcessor';

package/dist/src/manifest.d.ts

@@ -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.
  */

package/dist/src/manifestValidation.d.ts

@@ -64,10 +64,10 @@ 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)
  */
@@ -151,15 +151,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 in reverse-domain format (e.g. \"com.acme.app\")"
+ * // "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

@@ -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
  */
@@ -340,11 +317,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 */

package/dist/src/oqseValidation.d.ts

@@ -181,29 +181,6 @@ export declare const FeatureProfileSchema: z.ZodObject<{
     itemProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
     metaProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
-export declare const FeatureTypeSchema: z.ZodEnum<{
-    official: "official";
-    experimental: "experimental";
-    proprietary: "proprietary";
-}>;
-export declare const OfficialFeatureNameSchema: z.ZodEnum<{
-    math: "math";
-    "media-image": "media-image";
-    "media-audio": "media-audio";
-    "media-video": "media-video";
-    hotspots: "hotspots";
-    "complex-pairing": "complex-pairing";
-    "open-text": "open-text";
-}>;
-export declare const FeatureRequirementSchema: z.ZodObject<{
-    name: z.ZodString;
-    type: z.ZodEnum<{
-        official: "official";
-        experimental: "experimental";
-        proprietary: "proprietary";
-    }>;
-    vendor: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 export declare const TranslationObjectSchema: z.ZodObject<{
     lang: z.ZodString;
     id: z.ZodString;
@@ -322,15 +299,6 @@ export declare const OQSEMetaSchema: z.ZodObject<{
         itemProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
         metaProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
-    requiredFeatures: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        type: z.ZodEnum<{
-            official: "official";
-            experimental: "experimental";
-            proprietary: "proprietary";
-        }>;
-        vendor: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tagDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         wikidataId: z.ZodOptional<z.ZodString>;
@@ -491,7 +459,7 @@ export declare const PolygonHotspotSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
- * Mesh hotspot ��� references a named node/mesh in a 3D glTF scene.
+ * Mesh hotspot references a named node/mesh in a 3D glTF scene.
  * Used exclusively in `pin-on-model` items.
  */
 export declare const MeshHotspotSchema: z.ZodObject<{
@@ -550,7 +518,7 @@ export declare const CameraSetupSchema: z.ZodObject<{
 /**
  * Categorize item
  */
-export declare const CategorizeItemSchema: z.ZodObject<{
+export declare const CategorizeItemObjectSchema: z.ZodObject<{
     id: z.ZodString;
     text: z.ZodString;
     correctCategoryIndex: z.ZodNumber;
@@ -1683,7 +1651,7 @@ export declare const PinOnImageItemSchema: z.ZodObject<{
 /**
  * Categorize Item
  */
-export declare const CategorizeItemTypeSchema: z.ZodObject<{
+export declare const CategorizeItemSchema: z.ZodObject<{
     id: z.ZodString;
     assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
@@ -4280,15 +4248,6 @@ export declare const OQSEFileSchema: z.ZodObject<{
             itemProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
             metaProperties: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
-        requiredFeatures: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            type: z.ZodEnum<{
-                official: "official";
-                experimental: "experimental";
-                proprietary: "proprietary";
-            }>;
-            vendor: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tagDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             wikidataId: z.ZodOptional<z.ZodString>;

package/dist/src/richTextProcessor.d.ts

@@ -0,0 +1,46 @@
+import { FeatureProfile } from './oqse';
+export interface TokenMap {
+    [tokenId: string]: {
+        type: 'asset' | 'blank';
+        key: string;
+        originalTag: string;
+    };
+}
+export interface RichTextProcessingOptions {
+    /** * Function to parse Markdown to HTML (e.g., `marked.parse`).
+     * For Tier 1, this should ideally be configured to escape raw HTML.
+     */
+    markdownParser: (markdown: string) => string;
+    /** * Function to sanitize HTML (e.g., `DOMPurify.sanitize`).
+     * REQUIRED if the set declares the 'html' feature (Tier 2).
+     */
+    htmlSanitizer?: (html: string) => string;
+    /** Callback to render an <asset:key /> tag into HTML (e.g., <img src="...">) */
+    assetReplacer?: (key: string) => string;
+    /** Callback to render a <blank:key /> tag into HTML (e.g., <input type="text">) */
+    blankReplacer?: (key: string) => string;
+}
+/**
+ * Step 1: Tokenization.
+ * Temporarily replaces <asset:key /> and <blank:key /> with cryptographically safe
+ * text tokens so they survive Markdown parsing and HTML sanitization.
+ */
+export declare function tokenizeOqseTags(rawText: string): {
+    text: string;
+    tokens: TokenMap;
+};
+/**
+ * Step 2 (Tier 1): Strict HTML Validation.
+ * If 'html' is not allowed, any raw HTML tags written by the user must cause a validation error.
+ */
+export declare function validateTier1Markdown(textWithoutOqseTags: string): void;
+/**
+ * Step 4: Detokenization.
+ * Replaces the safe tokens back with the final interactive HTML elements.
+ */
+export declare function detokenizeOqseTags(safeHtml: string, tokens: TokenMap, options: Pick<RichTextProcessingOptions, 'assetReplacer' | 'blankReplacer'>): string;
+/**
+ * Main Facade for rendering OQSE Rich Content securely.
+ * Executes the complete Tokenization -> Validation -> Parsing -> Sanitization -> Detokenization pipeline.
+ */
+export declare function prepareRichTextForDisplay(rawContent: string, requirements: FeatureProfile | undefined, options: RichTextProcessingOptions): string;

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

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

package/dist/src/utils.d.ts

@@ -1,3 +1,12 @@
 export type UUID = string;
+/**
+ * Validates if the given string is a syntactically valid UUID (any version).
+ * Uses the robust validator from the 'uuid' package.
+ */
 export declare function isValidUUID(id: string): boolean;
+/**
+ * Generates a new UUIDv7.
+ * UUIDv7 is required by the OQSE specification for new items
+ * because it is time-sortable and optimized for database indexing.
+ */
 export declare function generateUUID(): UUID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memizy/oqse",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK and Zod validators for the OQSE specification.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,17 +17,19 @@
     "dist",
     "schemas",
     "README.md",
-    "SPECIFICATION.md"
+    "SPECIFICATION.md",
+    "LICENSE"
   ],
   "scripts": {
     "dev": "vite build --watch",
     "generate:schemas": "tsx scripts/generate-schemas.ts",
-    "build": "npm run generate:schemas && tsc && vite build",
+    "build": "npm run generate:schemas && tsc && vite build && tsx scripts/fix-types-entry.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/uuid": "^10.0.0",
     "tsx": "^4.21.0",
     "typescript": "~6.0.2",
     "vite": "^8.0.4",
@@ -35,6 +37,7 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
+    "uuid": "^13.0.0",
     "zod": "^4.3.6"
   }
 }

package/schemas/oqse-manifest-v0.1.json

@@ -38,8 +38,7 @@
         "features": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "latexPackages": {
@@ -52,15 +51,13 @@
         "itemProperties": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "metaProperties": {
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "actions": {

package/schemas/oqse-v0.1.json

@@ -239,8 +239,7 @@
             "features": {
               "type": "array",
               "items": {
-                "type": "string",
-                "minLength": 1
+                "type": "string"
               }
             },
             "latexPackages": {
@@ -253,48 +252,18 @@
             "itemProperties": {
               "type": "array",
               "items": {
-                "type": "string",
-                "minLength": 1
+                "type": "string"
               }
             },
             "metaProperties": {
               "type": "array",
               "items": {
-                "type": "string",
-                "minLength": 1
+                "type": "string"
               }
             }
           },
           "additionalProperties": false
         },
-        "requiredFeatures": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "name": {
-                "type": "string",
-                "minLength": 1
-              },
-              "type": {
-                "type": "string",
-                "enum": [
-                  "official",
-                  "experimental",
-                  "proprietary"
-                ]
-              },
-              "vendor": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "name",
-              "type"
-            ],
-            "additionalProperties": false
-          }
-        },
         "tags": {
           "type": "array",
           "items": {