feat(rune): add stepper-thumbnail render hook to opaque Rune values

[martin-henz]

Summary

Implements the rune-module side of #879: Rune's opaque value now optionally carries its own stepper-thumbnail renderer, so a future py-slang stepper can show a small inline picture instead of <opaque> text at each step - without any change to the module's public/student-facing API.

• RENDER_THUMBNAIL_SYMBOL (Symbol.for('source-academy.stepper.renderThumbnail')) lives in lib/modules-lib/src/conductor/thumbnail.ts so other modules (e.g. curve) can adopt the same convention later without importing from rune.
• attachThumbnailHook (src/bundles/rune/src/rune.ts, wired in at __makeRune) mutates the Rune instance in place via a non-enumerable Object.defineProperty - a copy/wrapper would silently break every downstream instanceof Rune check that later transforms (scale, stack, overlay, ...) rely on.
• renderRuneThumbnail renders via OffscreenCanvas + the existing DrawnNormalRune draw path (getWebGlFromCanvas/drawRunesToFrameBuffer widened to accept HTMLCanvasElement | OffscreenCanvas, no shader/buffer logic duplicated). OffscreenCanvas is the only rendering surface available in the module plugin's realm (a Web Worker - no document/DOM there), and isn't universally supported, so the hook is only attached when actually usable, and never throws on a failed render - a bad thumbnail must never surface as a runtime error to student code.
• THUMBNAIL_SIZE is a single exported constant (32px, chosen against the stepper's actual 16px monospace/~20px-line-height text scale) for easy retuning later.
• animate_rune/animate_anaglyph are explicitly out of scope here - they wrap pre-serialized frame data, not a live Rune, and "which frame to thumbnail" needs its own design decision as a follow-up.
• New docs page (docs/src/modules/5-advanced/conductor-interop/6-opaque-thumbnails.md, linked from the existing 3-opaque.md) documents the convention for future module authors.

This ships with no visible effect on its own. The stepper-side consumer (actually reading this property and rendering an <img>) lives in py-slang, is tracked there separately, and is itself gated on stepper import support (py-slang#385) landing first.

Test plan

• yarn workspace @sourceacademy/modules-lib tsc/lint/test pass
• yarn workspace @sourceacademy/bundle-rune tsc/lint/test pass (3 new tests: hook attached + non-enumerable when OffscreenCanvas is available, hook absent + no throw when unavailable, a failed render resolves to undefined rather than throwing)
• yarn workspace @sourceacademy/tab-Rune tsc/lint and its real-WebGL Playwright test suite pass - confirms the widened draw()/getWebGlFromCanvas types don't break the tab's existing live rendering
• Docs site builds cleanly with the new page
• Manually rendered heart, circle, and stack(red(heart), circle) through the actual hook in headless Chromium (real OffscreenCanvas + WebGL + convertToBlob) and confirmed valid, non-blank 32x32 PNGs come out the other end - not just a type-checked no-op

🤖 Generated with Claude Code

https://claude.ai/code/session_018BGtXu5xNkraFeG1BjSnLW

[martin-henz]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

Changes

Rune opaque thumbnails

Layer / File(s)	Summary
Thumbnail hook contract lib/modules-lib/src/conductor/thumbnail.ts, lib/modules-lib/src/conductor/__tests__/thumbnail.test.ts, docs/src/modules/5-advanced/conductor-interop/*	Adds the shared RENDER_THUMBNAIL_SYMBOL and documents the optional opaque-value thumbnail contract.
Rune thumbnail rendering src/bundles/rune/src/rune.ts, src/bundles/rune/src/functions.ts, src/bundles/rune/src/runes_webgl.ts	Adds OffscreenCanvas-compatible drawing and failure-safe PNG data URL rendering.
Rune integration and validation src/bundles/rune/src/index.ts, src/bundles/rune/src/__tests__/index.test.ts	Attaches thumbnail hooks before opaque conversion and tests conditional attachment, non-enumerability, cleanup, and failures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RuneModulePlugin
  participant attachThumbnailHook
  participant OffscreenCanvas
  participant DrawnNormalRune
  RuneModulePlugin->>attachThumbnailHook: wrap Rune before opaque_make
  attachThumbnailHook->>OffscreenCanvas: create 32x32 canvas
  OffscreenCanvas->>DrawnNormalRune: render Rune
  DrawnNormalRune-->>attachThumbnailHook: canvas output
  attachThumbnailHook-->>RuneModulePlugin: PNG data URL or undefined

Loading

Possibly related issues

• Runes: thumbnails for stepper #879: The PR implements the issue’s proposed Rune thumbnail hook, including OffscreenCanvas rendering and failure handling.

Suggested reviewers: leeyi45

Poem

A rabbit draws on canvas bright,
In offscreen hops beyond the light.
A symbol hides the tiny art,
PNG crumbs from Rune’s clever heart.
If render fails, it whispers: none.
Then bounds away when work is done.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the implementation, motivation, testing, documentation, and scope, although it does not reproduce all template checklist fields.
Title check	✅ Passed	The title clearly and concisely identifies the Rune stepper-thumbnail hook added to opaque values.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/rune-thumbnail-stepper-hook

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/modules-lib/src/conductor/thumbnail.ts`:
- Around line 15-19: Update the thumbnail-hook contract to consistently
represent render failure as undefined: in
lib/modules-lib/src/conductor/thumbnail.ts lines 15-19, state that failed
rendering returns or resolves to undefined; in
docs/src/modules/5-advanced/conductor-interop/6-opaque-thumbnails.md lines 19
and 34-35, change the result types to Promise<string | undefined> and () =>
Promise<string | undefined>, and require consumers to handle undefined.

In `@src/bundles/rune/src/__tests__/index.test.ts`:
- Around line 164-170: Extend the afterEach cleanup to save and restore the
property descriptor for RENDER_THUMBNAIL_SYMBOL on every shared RuneFunctions
instance, alongside the existing OffscreenCanvas restoration. Ensure descriptors
are captured before plugin.initialise() mutates the instances and restored or
removed as appropriate so tests cannot leak thumbnail hooks.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1c009383-3d02-4b6d-ae68-59a7d0dfce93

📥 Commits

Reviewing files that changed from the base of the PR and between 049a34b and 4902b29.

📒 Files selected for processing (9)

• docs/src/modules/5-advanced/conductor-interop/3-opaque.md
• docs/src/modules/5-advanced/conductor-interop/6-opaque-thumbnails.md
• lib/modules-lib/src/conductor/__tests__/thumbnail.test.ts
• lib/modules-lib/src/conductor/thumbnail.ts
• src/bundles/rune/src/__tests__/index.test.ts
• src/bundles/rune/src/functions.ts
• src/bundles/rune/src/index.ts
• src/bundles/rune/src/rune.ts
• src/bundles/rune/src/runes_webgl.ts