Conductor migration: audit API differences + VitePress docs migration (student facing)

[Akshay-2007-1]

Follow-up from #824 (pix_n_flix Conductor migration). The module's API changed in a few ways during the migration, some restored, some gone for good, and probably some we haven't found yet. Opening this to track that properly instead of leaving it as tribal knowledge in a PR thread.

What's already restored, same as before

red_of, green_of, blue_of, alpha_of and set_rgba are back with their original signatures and the same 0-255 value range (checked against both the old source and the currently published docs). They're built on top of the new get_pixel_value/set_pixel_value, so nothing content-facing needs to change for these five.

What's new and unavoidable

get_pixel(image, x, y) is a new function replacing direct src[x][y] indexing wherever code needs to grab a pixel. Old code that indexed straight into a source/destination image is broken and can't be fixed on our side: opaque image handles just aren't indexable at the language level in either py-slang or js-slang, and getting that working again would mean changing the interpreters themselves, not something to do at the module level.

This isn't hypothetical. There's at least one public old mission (Zeepheru/cs1101s, missions/18_StreamingTheAnomaly.js) that does exactly this directly:

dst[i][j] = current_img[i][j];

Since Python support for pix_n_flix is brand new as of this migration, this only affects existing Source (JS) content, nothing Python-side existed to break.

What we're asking for

Someone who knows what pix_n_flix content currently exists (missions/quests/paths) needs to actually check what's out there, not just the double-indexing case above. There's very likely other stuff we haven't hit yet: subtle behavior changes, edge cases, things that quietly work differently now. This issue is meant to track that audit rather than close it.

Also worth considering

A lot of the confusion here comes from docs that were written entirely from the Source (JS) side. Might be worth having a proper Python-facing section or page for modules going forward, since stuff like get_pixel's usage, or general Python-crossing-the-boundary gotchas (numbers always coming back as float, not int, being a common one), don't really have a natural home in the current docs.

[Akshay-2007-1]

Went through the rest of the old functions.ts line by line against the new one, found a few more real differences worth tracking here:

1. start() is gone entirely

In the old module, install_filter only registered the filter, you had to call start() separately afterward to actually kick off the feed. The new module folds that into install_filter itself, so start() was dropped from the exports.

Any old code that calls start() explicitly will now get an undefined-function error. This is probably the single most likely thing to break existing content, more so than the pixel-indexing stuff.

2. install_filter/compose_filter lost their arity check

The old code explicitly verified a passed filter took exactly 2 parameters and threw a clear error immediately if not:

export function install_filter(_filter: Filter): void {
  assertFunctionOfLength(_filter, 2, install_filter.name, 'filter');
  filter = _filter;
}

The new code doesn't check this at all, so a wrong-arity filter now only fails later, on the first captured frame, with a generic error instead of a clear one at install time.

3. copy_image is now stricter

The old version just assumed src and dest matched the module's current width/height with no check at all. The new version actually validates both images are the same size and throws if not. This is a safety improvement, not a break, but it's a behavior change worth knowing about.

4. pause_at quietly lost its integer requirement

The old validation required pause_time to be a whole number (through a default in its validation helper). The new one only checks it's non-negative, so a fractional millisecond value that used to error now silently works. Minor, unlikely to break anything, but different.

---

Still can't promise this is everything. Whoever ends up doing the actual content-side check should probably not treat this list as final.

[Akshay-2007-1]

What we're asking for

Someone who knows what pix_n_flix content currently exists (missions/quests/paths) needs to actually check what's out there, not just the double-indexing case above. There's very likely other stuff we haven't hit yet: subtle behavior changes, edge cases, things that quietly work differently now. This issue is meant to track that audit rather than close it.

@leeyi45, could you review #824 with regards to the above? Besides do you approve of the following (mentioned above as well). @martin-henz, any thoughts here?

What's new and unavoidable

get_pixel(image, x, y) is a new function replacing direct src[x][y] indexing wherever code needs to grab a pixel. Old code that indexed straight into a source/destination image is broken and can't be fixed on our side: opaque image handles just aren't indexable at the language level in either py-slang or js-slang, and getting that working again would mean changing the interpreters themselves, not something to do at the module level.

[Akshay-2007-1]

Also worth considering

A lot of the confusion here comes from docs that were written entirely from the Source (JS) side. Might be worth having a proper Python-facing section or page for modules going forward, since stuff like get_pixel's usage, or general Python-crossing-the-boundary gotchas (numbers always coming back as float, not int, being a common one), don't really have a natural home in the current docs.

@martin-henz, I prefer that we have a new documentation site for Python Modules and not the current version. We had done the same for py-slang README as well here where we added a new /python/ subpath.

I am saying this as many of the sample test snippets as well as some considerations above demand the same to be Python specific! If one exists somewhere already (and I missed it), I apologize!

[leeyi45]

Also worth considering

A lot of the confusion here comes from docs that were written entirely from the Source (JS) side. Might be worth having a proper Python-facing section or page for modules going forward, since stuff like get_pixel's usage, or general Python-crossing-the-boundary gotchas (numbers always coming back as float, not int, being a common one), don't really have a natural home in the current docs.

@martin-henz, I prefer that we have a new documentation site for Python Modules and not the current version. We had done the same for py-slang README as well here where we added a new /python/ subpath.

I am saying this as many of the sample test snippets as well as some considerations above demand the same to be Python specific! If one exists somewhere already (and I missed it), I apologize!

I don't think we need to "redo" the docs and have it as a subsite: Vitepress already very nicely handles situations where you need to choose between different versions on the same site (Vitepress' own site allows you to choose between 1.6 and 2.0-alpha)

We would probably need to create a Markdown theme for Module documentation specifically, but it can be done.

From what I understand we would need a way to specify which examples apply for what language, and a way to convert between the implementation and the rendered language (i.e convert a Typescript declaration to Python).

[Akshay-2007-1]

@leeyi45 and I had decided on an interim given the urgency and deadline for the upcoming semester. We will be making a site-wide dropdown between Source and Python at https://source-academy.github.io/modules/documentation/ while delaying the Vitepress server docs design work to be parallel and non-blocking.

Since changing the language changes the entire displayed content, we would be able to display above such API diffs for specific modules to the students EXPLICITLY based on the language being used!

[Akshay-2007-1]

I will be working on the interim where we merely make convertors for typedoc to display Python snippets and Python content for only the modules we have migrated as of now over at the older site itself! The rest of the discussion (although still valid) will be postponed and worked on eventually!

[Akshay-2007-1]

The current situation has changed and due to the time constraints, we were only able to get the docs migrated for those modules which have been conductor migrated. The rest are all hidden in a way from the index.

Inside the API docs as well, no code snippets are provided. This was tracked earlier in #886 but we decided on making the docs language agnostic as well with code appropriate with all supported language at the same place.

This is pfc better supported with a looser (in a way) framework, VitePress for docs instead of TypeDocs.

So this will be an addition to that work left unhandled for now.