# Stage 5 — Arabic, RTL, and Pre-Conversion Font Uploads

## Status

Stage 5 implementation is in progress; do not declare full acceptance yet.

Implemented: explicit preparing-project workflow, font/preparation APIs and revisions, private static TTF/OTF validation, family/style/theme inventory, separate rendering/player settings, Linux helper and Windows Docker image, per-job Fontconfig/profile/cache isolation, generation snapshots and safe publication, failed-generation preservation, dirty-image package blocking, configuration version 4 and local learner dictionaries. Application-owned authoring labels, account pages and preparation use English/Arabic translations. Authored content is not translated.

The three additive migrations were applied locally on 2026-09-13 without resetting existing data. Docker Desktop's Linux engine was started and the version-1 renderer image was built locally. The real Windows Docker Arabic/OTF render-to-package test passed. Python tests passed for explicit-format/source preservation, external-entity rejection and concurrent conflicting-family font isolation.

Browser checks verified persisted Arabic preferences, independent English/LTR rendering and player settings, preserved authored titles, and no horizontal overflow at desktop and 390-pixel mobile viewports. These checks do not constitute full keyboard or learner acceptance.

Acceptance remaining: native Ubuntu execution under the deployment worker account; author-supplied PowerPoint reference exports; complete browser RTL, mixed-text and keyboard testing; Moodle/offline Arabic SCORM acceptance; audit remaining dynamic messages and controls for translation completeness. Existing unfinished multimedia work remains preserved and is not declared complete.

See [renderer setup](stage-05-local-setup.md) for installation and worker commands.

## Summary

Support Arabic and English throughout DocuDeck and its learner player. Allow authors to upload the fonts used by their PowerPoint presentation before conversion to improve rendered slide fidelity, especially Arabic text shaping, spacing, wrapping, and alignment.

Correct fonts improve fidelity but do not guarantee pixel-identical Microsoft PowerPoint output. LibreOffice rendering differences in layout, effects, charts, and other presentation features can remain.

## Arabic and RTL

Keep these settings independent:

| Setting | Purpose |
| --- | --- |
| Application language: English / العربية | Login, registration, dashboard, account pages, editor, validation, and status messages |
| Course player language: English / العربية | Learner controls, question interface, feedback labels, review, and completion messages |
| Course direction: Auto / LTR / RTL | Learner interface and authored text layout |

### Application experience

- Provide an accessible English/Arabic language switcher.
- Translate user-facing labels, messages, empty states, errors, confirmations, and processing states.
- Use RTL layouts for the Arabic application interface.
- Preserve readable mixed Arabic/English text, URLs, email addresses, numbers, and filenames.
- Use direction-aware spacing and alignment rather than duplicating entire layouts.
- Mirror directional navigation where appropriate, without mirroring media controls or unrelated icons indiscriminately.
- Define and document how language preferences persist and how Auto direction is resolved before implementation.

### Course authoring and learner player

- Support Arabic titles, questions, answers, feedback, transcripts, and media-button labels.
- Apply course language and direction consistently in author preview and packaged SCORM.
- Include Arabic interface translations locally in the SCORM package so uploaded-media courses can operate offline.
- Keep existing English projects backward compatible with their current behavior.
- Never mirror original slide images. Their text direction and layout come from the source presentation.
- Interface localization does not translate presentation content automatically.
- Verify keyboard navigation, focus order, accessible names, and screen-reader language attributes in both languages.

## Pre-Conversion Font Preparation

New uploads return 202 with preparing status. Rendering begins only after the author reviews fonts and rendering defaults and explicitly requests image generation.

```text
Select PowerPoint
→ Inspect presentation and referenced fonts
→ Upload missing font files
→ Review font matches and warnings
→ Start conversion
→ Review rendered slides
```

### Font inspection

- Inspect font references in presentation text, themes, masters, and layouts where supported.
- Resolve theme references rather than displaying only theme aliases.
- Read uploaded font metadata: internal family name, style, and weight.
- Match by font metadata rather than assuming the filename is the family name.
- Display available, uploaded, missing, and substituted font status.
- Warn when required styles or weights, such as Bold or Italic, are missing.
- Report inspection limitations honestly; do not claim all fonts were detected if unsupported structures remain.
- Show Arabic and English sample text using suitable validated preview handling.

### Font uploads

- Initially accept validated TTF and OTF font files.
- Allow multiple fonts, including separate family weights and styles.
- Allow removing or replacing fonts before conversion.
- Keep files private, owned by the project/account, and available for later re-rendering.
- Require author confirmation that they have permission to upload and use the fonts.
- Enforce 10 MB/file, 100 MB/project and 50 files; only static TTF/OTF are accepted.
- Validate actual font structure, not only extension or browser MIME type.
- Reject malformed fonts and unsupported formats with clear localized messages.
- Do not install uploaded fonts globally on the server.

### Repository examples

The `examples fonts` folder currently contains examples including:

- `WinSoft Pro Medium.ttf`
- `Myriad Headline.otf`
- `GE_SS_Two_Light.otf`
- Additional TTF, WOFF, and WOFF2 files.

These are format examples, not proof of internal family names, Arabic coverage, licensing permission, or successful rendering. Inspect their metadata and validate their use during implementation.

WOFF/WOFF2 conversion and support remain deferred for the initial version. They must not be advertised as supported presentation-rendering inputs without a tested conversion/loading strategy.

## Rendering and Isolation

### Ubuntu production

- Investigate a per-conversion Fontconfig configuration pointing to the project's validated fonts and approved system fallback fonts.
- Use private job-specific configuration and caches where required.
- Verify that the actual LibreOffice rendering process sees the intended family names and styles.
- Test concurrent jobs with conflicting font-family names to prove that projects cannot affect each other.
- Do not assume an isolated LibreOffice user profile alone isolates font discovery.

### Windows / Laragon

- Use the version-tagged Docker Linux renderer and the same helper contract as Ubuntu.
- Avoid system-wide installation of untrusted project fonts.
- If safe isolation cannot be supported initially, document the limitation explicitly instead of claiming parity with Ubuntu.

### Saved projects and re-rendering

- Preserve uploaded fonts with the project for future conversion retries and re-rendering.
- Re-rendering must preserve authored course settings, questions, media, and course flow where their slide references remain valid.
- Define handling for slide-count or slide-order changes before supporting source replacement.
- Invalidate generated packages when rendered slides change.
- Prevent font changes from racing an active conversion job.
- Permanent project deletion must clean up uploaded fonts and related metadata.

## Packaging

- Store course language and direction in versioned course configuration.
- Package the required English/Arabic interface resources.
- Do not package uploaded presentation fonts for image-only slide playback: their rendered appearance is already contained in slide images.
- Any future live-text rendering/font redistribution needs separate technical and licensing handling.
- Preserve existing SCORM 1.2 progress, questions, multimedia tracking, resume, completion, and scoring behavior.

## Security and Reliability

- Enforce project ownership for inspection, upload, replacement, removal, and re-render operations.
- Block edits to archived projects until restored.
- Keep uploaded fonts outside public web directories.
- Apply resource limits and timeouts to font parsing and presentation rendering.
- Use safe generated storage paths rather than uploaded filenames.
- Avoid arbitrary global font substitution and silently modifying source text.
- Provide warnings and an explicit choice when fonts are missing; finalize whether conversion may proceed with fallback fonts.
- Ensure queued jobs safely handle deleted projects and missing font files.

## Testing and Acceptance

- Test application language switching and RTL layout on desktop and mobile.
- Test Arabic/English mixed content, punctuation, numerals, URLs, filenames, and form validation.
- Test questions, media labels, transcripts, review, and completion screens in Arabic.
- Test preview and packaged-player language/direction consistency.
- Test valid TTF/OTF uploads, malformed files, ownership, limits, duplicates, style matching, and missing-font warnings.
- Test theme-font resolution and representative Arabic presentations.
- Compare rendered output with a reference exported from Microsoft PowerPoint using the same fonts.
- Test isolated concurrent conversions and font reuse during retry/re-render.
- Test project restoration, archive restrictions, and deletion cleanup.
- Test offline SCORM interface translations and Moodle SCORM 1.2 behavior.
- Preserve Stage 1–4 regression tests.

## Deferred Work

- Automatic content translation.
- WOFF/WOFF2 conversion and presentation-rendering support.
- Automatic commercial-font downloads or font licensing procurement.
- Global shared font installation from user uploads.
- Guaranteed pixel-identical Microsoft PowerPoint rendering.
- Font redistribution for future editable/live-text slide rendering.

## Finalized contract

English/LTR defaults. Application, rendering and learner languages remain independent. Auto resolves from the corresponding language. Presentation text is never translated and images/video are never mirrored. Temporary-source defaults are applied at presentation-level default text style, keeping direct/layout/master formatting at higher priority and preserving explicit attributes.

Static TTF/OTF limits are 10 MB/file, 100 MB/project and 50 files. WOFF/WOFF2, collections and variable fonts are rejected. Font use requires permission acknowledgement. Missing/style-mismatched fonts and unresolved references require substitution acknowledgement with the current preparation revision.

Ubuntu runs the Linux helper directly. Windows preparation uses the version-tagged Docker Linux image and the same helper. Native Windows LibreOffice is a legacy path only. Uploaded matching family/style selection is checked with the job's Fontconfig configuration before rendering. Preview display is not a guarantee of LibreOffice selection.

Regeneration uses the saved original only, stages immutable generation outputs, verifies slide counts/images and publishes under a conversion lock. It preserves course settings/questions/media/flow and invalidates the package only after success. Failed regeneration retains previous slides/package, including legacy projects. Changed preparation blocks new packaging; retained packages remain downloadable. Active rendering/packaging serializes authoring writes.

### Authenticated APIs

All routes below are under /api/v1/powerpoint-to-scorm/conversions/{id}:

- GET /fonts — settings/revision, uploaded fonts, detected references, warnings, limits and renderer capabilities.
- PUT /preparation — revision-checked rendering language/direction.
- POST /fonts/uploads — validated upload with revision and permission_acknowledged.
- DELETE /fonts/{font} — revision-checked removal.
- GET /fonts/{font}/preview — owner-only private font response for browser samples.
- POST /render — explicit initial generation or regeneration with revision and fallback_acknowledged.

Stale revisions and active-operation conflicts return 409. Unavailable rendering returns 503 without fallback. Font/ownership/archive/deletion checks remain enforced. Selected fonts/settings/revision are snapshotted for each generated UUID; stale/deleted jobs cannot publish. Project deletion removes fonts and generation directories through the existing private project-root cleanup.

## Technical References

- [LibreOffice font substitution](https://help.libreoffice.org/latest/en-US/text/shared/optionen/01010700.html)
- [Fontconfig configuration documentation](https://fontconfig.pages.freedesktop.org/fontconfig/fontconfig-user.html)
- [LibreOffice font embedding and licensing flags](https://help.libreoffice.org/latest/en-US/text/shared/01/prop_font_embed.html)