Harden Lildra layout and refresh branding

2026-07-27 19:00:22 +10:00
parent e6e5336209
commit 433c73a77c
11 changed files with 238 additions and 106 deletions
@@ -0,0 +1,47 @@
+# Lildra contributor instructions
+
+## Purpose and product boundaries
+
+Lildra is a deliberately small Chrome/Edge Manifest V3 extension for distraction-free reading on Canvas/QLearn course lesson and wiki pages. It hides Canvas navigation, keeps the native lesson content at a centred reading width, and adds only a title bar and version label.
+
+Never move, clone, wrap, or reconstruct lesson DOM. Never restyle lesson typography, headings, images, links, tables, embeds, or user content. Keep selectors limited to known Canvas shell elements and guarded by strict page detection. Do not broaden activation to dashboards, assignments, discussions, quizzes, modules, account pages, or arbitrary websites.
+
+Do not add frameworks, build tools, dependencies, analytics, telemetry, remote scripts, content delivery networks, settings pages, options pages, popup interfaces, accounts, storage, or unrelated features. Do not add persistent host permissions when `activeTab` is sufficient.
+
+## Architecture
+
+- `manifest.json` defines the MV3 service worker, toolbar action, Alt+L command, permissions, and icons.
+- `background.js` handles the toolbar and command, then injects `lildra.js` into the active tab.
+- `lildra.js` validates the URL and Canvas DOM, injects scoped layout CSS and two inert UI elements, watches for dynamic title changes, and owns complete toggle cleanup.
+- `icons/` contains the packaged toolbar/store icons.
+
+There is intentionally no content script registered for persistent execution. Re-injecting `lildra.js` toggles the current page off through its page-scoped state object.
+
+## Coding standards
+
+- Use dependency-free, modern JavaScript supported by current Chrome and Edge.
+- Keep strict mode enabled and avoid leaking globals except the single toggle state key.
+- Scope every CSS rule under `html.lildra-active` and target Canvas shell IDs/classes narrowly.
+- Treat injected visual labels as decorative when equivalent page information already exists, so screen readers do not receive duplicate landmarks or titles.
+- Read package metadata from `chrome.runtime.getManifest()`; do not duplicate the version in JavaScript or CSS.
+- Preserve cleanup symmetry: every observer, class, style, and element added on enable must be removed on disable.
+- Prefer clear names and comments that explain constraints, not obvious syntax.
+
+## Test procedure
+
+Before release:
+
+1. Parse `manifest.json` and confirm every referenced JavaScript and icon file exists.
+2. Load the unpacked extension in current Chrome and Edge with no extension errors.
+3. On a QLearn lesson page, toggle on and off with both the toolbar button and Alt+L.
+4. Confirm the global and course navigation hide, lesson content remains centred at its normal bounded width, and no lesson content styling or DOM position changes.
+5. Test long and dynamically rendered titles; confirm centring, one-line ellipsis, and title updates.
+6. Test desktop and narrow/mobile-width viewports, including pages with tables, images, links, and embeds.
+7. Confirm `Lildra vX.Y.Z` matches `manifest.json` and remains unobtrusive.
+8. Try dashboards, module lists, assignments, discussions, quizzes, non-content page routes, HTTP pages, and unrelated sites; Lildra must not activate.
+9. Navigate between Canvas pages without a full reload and confirm no stale title or injected UI remains.
+10. Check keyboard-only use and a screen reader for duplicate announcements or lost access to lesson content.
+
+## Versioning and releases
+
+Use Semantic Versioning. Change the version only in `manifest.json`: patch for fixes, minor for backward-compatible behaviour, and major for incompatible product changes. Move completed notes from `Unreleased` into a dated version section in `CHANGELOG.md`. Never commit packaged ZIP files. Do not commit or push unless the user explicitly requests it.