Optimizing Briefcase Web Development

[mEp3ii2]

Hi team,

After working on some of the web widgets for Toga, I’ve come to find that we could improve the local development experience to reduce wait times when testing changes to the web platform
Currently, when we want to test out some code changes we need to run:
briefcase run web -r -u
This is leading to a full wheel rebuild every time, even if only a single file has been changed.

This slows down local development, making it cumbersome for contributors working on the web backend.

Proposed Exploration Areas

We’re hoping to prototype several ideas to improve development speed and ergonomics when working on Briefcase web apps:

1. Selective Rebuilds

Goal: Detect what files have actually changed and only rebuild the necessary wheels.

Approaches:

• Scan file modification timestamps to determine what needs rebuilding.
• Add CLI flags:
  • --skip-rebuild-x
  • --rebuild-x

Questions for Discussion:

• Is there an architectural reason why full rebuilds are currently required, even if only a single file changes?
• Could selective rebuilding introduce subtle issues if not all wheels are refreshed together?

2. Implementation of --dev Mode for Web

Context:
Briefcase already supports a --dev mode flag for desktop platforms. Bringing this to the web backend would be a meaningful step forward.

Idea:

• Avoid wheel building/compression during development.
• Directly reference live source directories instead of packaging them.
• Potential use of a config/manifest to define paths (e.g., src/, toga/web/, etc.).
• This assumes that file contents change more frequently than the project’s structure.

3. Live Updating / Auto Reloading

"Nice to have" feature built on top of selective rebuilds and dev mode.

Potential Approaches:

• Use a watcher to monitor source files for changes.
• On change, either:
  • Restart the local HTTP server, or
  • Trigger a browser reload.
• Could be an opt-in feature via a flag:
  • --live
  • --reload

Goals

At a minimum, we hope to improve development speed by reducing unnecessary rebuilds.
And hopefully extend the existing --dev mode to fully support web projects.

We understand that these changes will require proper architectural considerations and are hoping to be able to work on prototyping some ideas over the coming weeks.

Feedback

Are there any parts of this proposal that weren’t clear or need further explanation?

Do you have any questions, concerns or advice about any of the ideas we’ve outlined?

Are there alternative approaches we might have missed that could help improve the web development workflow?

Open to suggestions and want to make sure we’re aligned with both Briefcase’s design goals and the needs of the broader community. Please feel free to share any thoughts, even small comments or side ideas could help shape what we prototype next.

Myself and @JMah007 will be looking into this as part of our University work this year and our hoping to conclude our research and some initial prototyping by the end of the semester in June and then finalizing this in the following semester.

[freakboy3742]

This slows down local development, making it cumbersome for contributors working on the web backend.

Completely agreed. The web developer experience isn't great right now - the turnaround from "oh, make a 1 character change to toga-web" and seeing that update take effect is much longer than is desirable.

1. Selective Rebuilds

Goal: Detect what files have actually changed and only rebuild the necessary wheels.

Approaches:

• Scan file modification timestamps to determine what needs rebuilding.

Agreed that this is a possible approach - albeit one that is mildly complicated to implement.

• Add CLI flags:

  • --skip-rebuild-x
  • --rebuild-x

I'm not wild about the idea of complicating the user interface to simplify one specific aspect of web development.

Questions for Discussion:

• Is there an architectural reason why full rebuilds are currently required, even if only a single file changes?

The primary reason a full rebuild is required at present is that wheels are used for delivering all the content of the web app. Building the wheel effectively requires a rebuild, as the PEP 517 wheel-building interface doesn't have an "incremental build" option.

In a normal desktop environment, there's 2 ways to install a package from a local source directory:

1. pip install /path/to/library - a standard install, which will create a full wheel, and then install that wheel
2. pip install -e /path/to/library - an "editable" install. This drops a .pth file in the installation location, which is a trigger to Python's import infrastructure to use code from a different location on disk.

Briefcase's web backend doesn't currently have an equivalent of an "editable" install, or an ability to deliver content the web backend in a format other than a wheel.

Pyscript, on the other hand, can reference individual files. That capability might form the basis of injecting python content into the web page.

• Could selective rebuilding introduce subtle issues if not all wheels are refreshed together?

I'll stand corrected if you find an example, but I doubt it. In order to test a change in a web app, or in toga-core or toga-web, you need to re-load the page. That re-initializes the entire application state. The only place this might be a problem is if the browser caches a file - but that should be something that the web server and browser are negotiating.

2. Implementation of --dev Mode for Web

Context: Briefcase already supports a --dev mode flag for desktop platforms. Bringing this to the web backend would be a meaningful step forward.

+1 to all this. There's obviously details to sort out, but AFAICT they're largely constrained by what options exist for defining content in PyScript, and/or what options for optimising which packages need to be rebuild.

One open question is exactly how this would be "spelled". Can this be put into an option on briefcase dev (i.e., briefcase dev --mode=web)? If so, how does the interface for this work as a point of extensions - i.e., can a particular backend (such as the web backend) provide overrides for how "dev mode" works?

Or does the dev command need to start honoring platform choices (i.e., briefcase dev on a MacBook would be a shorthand for briefcase dev macOS app; and thus briefcase dev web would also work)?

Or do we need to move "developer mode" into an option on the run command? (i.e., briefcase run --dev or briefcase run web --dev?

3. Live Updating / Auto Reloading

"Nice to have" feature built on top of selective rebuilds and dev mode.

Definitely a nice to have feature; but also something we can defer discussion until we have the previous two features working.

Goals

At a minimum, we hope to improve development speed by reducing unnecessary rebuilds. And hopefully extend the existing --dev mode to fully support web projects.

One detail worth pointing out here - if we have a dev mode that has a fast turnaround cycle for app code and for any local dependency specified as a file path (i.e., the "developing Toga" use case), the importance of a fast rebuild cycle for wheels is a lot less significant.

There's definitely an inefficiency in the run web command at present - both the app and the dependency wheels are rebuilt every time regardless; the dependencies should only be rebuilt if -r is specified. However, the need for a deeply optimised rebuild mechanism is a lot less important if we have a dev mode that is able to point directly at source files without rebuilding the wheel at all.

[freakboy3742]

So my though process is have the dev command look for existing .pth files or create the necessary editable installs if needed. Then, the dev server would serve the source files directly by following the paths specified in those .pth files. As users make changes to the source files they can then refresh the browser and changes will be displayed.

This depend a little on how the dev web server is set up. In a "desktop" dev, you're using the virtual environment that where Briefcase is installed, so the environment is a "normal" Python virtualenv. In normal "web" run, you're installing the full wheel into a static/wheels folder, and passing those files to pyodide as something that needs to be installed. For dev web, you'll need to start a web server... but where is it serving the raw files from? Is it using the briefcase venv? Creating a new one? Installing into a temporary directory?

This might require a little more research from me and @JMah007 but I'm confident that this should work

I have every confidence you'll be able to get it to work, but it would be good to have some indications of the ideas/approaches you'll be exploring, even if they're not 100% nailed down.

[JMah007]

So my though process is have the dev command look for existing .pth files or create the necessary editable installs if needed. Then, the dev server would serve the source files directly by following the paths specified in those .pth files. As users make changes to the source files they can then refresh the browser and changes will be displayed.

This depend a little on how the dev web server is set up. In a "desktop" dev, you're using the virtual environment that where Briefcase is installed, so the environment is a "normal" Python virtualenv. In normal "web" run, you're installing the full wheel into a static/wheels folder, and passing those files to pyodide as something that needs to be installed. For dev web, you'll need to start a web server... but where is it serving the raw files from? Is it using the briefcase venv? Creating a new one? Installing into a temporary directory?

This might require a little more research from me and @JMah007 but I'm confident that this should work

I have every confidence you'll be able to get it to work, but it would be good to have some indications of the ideas/approaches you'll be exploring, even if they're not 100% nailed down.

After discussion we would much prefer dev web to serve from Briefcases' venv just for simplicity. If its currently working for "desktop" dev with no issues then it just makes sense to do so. This will allow us to stay focused on the main optimisation objective.

Since this method has only been implemented on desktop platform and not web, are there any other considerations we should thinking about? Is there a major reason why dev on desktop uses Briefcase' venv instead of creating a new one for isolation?

[freakboy3742]

After discussion we would much prefer dev web to serve from Briefcases' venv just for simplicity. If its currently working for "desktop" dev with no issues then it just makes sense to do so. This will allow us to stay focused on the main optimisation objective.

So - there will be some complications:

Firstly - how to serve the contents of the venv to the browser? The current briefcase run web is based on putting everything you need into wheels, in a known location on the filesystem.; The location of site-packages in a venv is knowable, but isn't quite as obvious as "a directory that was created by Briefcase as part of a template".

Secondly - what happens with platform-specific wheels? If you pip install numpy into the briefcase dev environment, you'll get the macOS wheels. But, if you're deploying for web, you'll need the Pyodide wheels.

Third - how do you differentiate between "things Briefcase installed" and "things installed to support Briefcase"? For example, the current development venv will include GitPython, and on macOS, dmgBuild. Those tools won't work at all in web - but they will be in your site-packages folder. How do you determine which files will (and which won't) be served to the browser?

Since this method has only been implemented on desktop platform and not web, are there any other considerations we should thinking about? Is there a major reason why dev on desktop uses Briefcase' venv instead of creating a new one for isolation?

Desktop dev uses the existing venv because creating a new venv and updating dependencies is a moderately time-expensive operation; give you have an existing venv, it made sense (at the time) to just use the environment you already have, rather than create a new one.

That said: using the Briefcase environment does lead to issues. Most notable of these is that if you pip install toga, briefcase dev will find toga... but briefcase run won't, because you haven't declared Toga in your requirements. Forcing the use of a standalone dev environment would make it clear that "installing" means "adding to requires".

There's also the potential that a requirement constraint imposed by Briefcase could conflict with the requirements of a dependency (e.g., Briefcase requires psutil >= 5.9; if an app dependency requires psutil < 5.9, the environment would be unsolvable). We haven't seen this in practice to date, but it could happen.

There has been discussion about using a standalone venv for running dev - see #1735. I'm increasingly convinced this would be a good idea; so if it makes briefcase dev web easier to implement, then it might make sense to include change as part of this work (or to make it a feature of briefcase dev web in such a way that it could be added to briefcase dev in future).

[mEp3ii2]

Firstly - how to serve the contents of the venv to the browser? The current briefcase run web is based on putting everything you need into wheels, in a known location on the filesystem.; The location of site-packages in a venv is knowable, but isn't quite as obvious as "a directory that was created by Briefcase as part of a template".

Briefcase's venv might seem like the simpler approach at first but their is certain constraints introduced in regards to the web environment. Pyscript only supports pure Python files that can be fetched and loaded into its virtual filesystem.
So its probable better to have a clean dev venv constructed and maintained by the web dev mode.

Secondly - what happens with platform-specific wheels? If you pip install numpy into the briefcase dev environment, you'll get the macOS wheels. But, if you're deploying for web, you'll need the Pyodide wheels.

Third party libraries will be declared in the pyscript.toml and then fetched at runtime by Pyodide which will install the .whl files
loadPackage API

Overall after some more research I believe that its best to use a seperate venv for supporting the web dev mode

[freakboy3742]

Secondly - what happens with platform-specific wheels? If you pip install numpy into the briefcase dev environment, you'll get the macOS wheels. But, if you're deploying for web, you'll need the Pyodide wheels.

Third party libraries will be declared in the pyscript.toml and then fetched at runtime by Pyodide which will install the .whl files loadPackage API

That's definitely how Pyscript works... but it's not how Briefcase works when it comes to dependencies. In fact, I think you'll find that right now, Briefcase can't support binary dependencies on web.

Overall after some more research I believe that its best to use a seperate venv for supporting the web dev mode

Agreed.

[mEp3ii2]

So I believe at this stage it's worth putting out a revised proposal based on the changes and conclusions drawn so far

Proposal: Platform-Aware briefcase dev & Editable Installs for Web

To improve the local development experience when working on web projects, we propose extending Briefcase's dev command to support the web platform. This will allow for faster iteration cycles by eliminating the need to rebuild wheels and restart the app after every code change

With this, we aim to make the dev command platform aware, and make it so the web version uses .pth files and editable installs instead of .whl packages. By serving files directly into the browser via symlinks, developers will be able to make changes and see them reflected immediately upon refreshing the browser, which will help reduce wait times during development.

1. dev venv

We'll need to set up a dedicated dev venv that contains only the pure Python modules we need to serve, like Toga modules, which we'll install as editable installs.
The WebDevCommand will initialise a dedicated venv for the handling web dev mode(will implement a check if one exists and handling for users to force a refresh) in this venv we'll handle the installing of the application and its requirements as editable pip installs then upon launching read the .pth files and symlinks the reference packages into the projects www directory.

2. Third part libraries

3rd party libraries like 'numpy' and 'pandas' aren't pure Python. In the browser, Pyodide can't run these directly, so it requires .whl files. Pyodide micropip can dynamically fetch these WASM-compatible wheels at run time.

3. Use of .pth files for dynamic source mapping

Editable installs create .pth files in the venv that act as a reference to the actual source folder on the machine. In dev mode, we'll configure the dev server to read these .pth files and dynamically serve the latest versions of the Python modules they reference. This means any changes to Toga's source code are available in the browser without needing a rebuild or copying of files, just a refresh

4. Serving Toga Python modules to the browser for PyScript

To make Toga's Python modules available to PyScript in the browser, we'll serve them as standard .py files from our static assets directory. These files are loaded directly into the in-browser virtual filesystem described in PyScript Filesystem Guide, allowing PyScript to import and execute them as regular Python modules during runtime. This avoids the need for additional packaging steps

Outcome

With this approach, we hope that it will result in:

• A platform-aware briefcase dev command that supports web
• Faster feedback loops for web development

Breakdown of tasks

The work can be mainly broken down into 3 parts

1. Enable Platform-aware dev commands
2. Get local Python files into the venv and serve them to the browser
3. Handle 3rd-party dependencies via Pyodide

These can all be further broken down into smaller subtasks, but this covers the general scope of work being done.

@JMah007 let me know if there's anything you want me to add or if I missed anything
@freakboy3742 please provide your thoughts and any feedback or recommendations

[freakboy3742]

So I believe at this stage it's worth putting out a revised proposal based on the changes and conclusions drawn so far

Proposal: Platform-Aware briefcase dev & Editable Installs for Web

To improve the local development experience when working on web projects, we propose extending Briefcase's dev command to support the web platform. This will allow for faster iteration cycles by eliminating the need to rebuild wheels and restart the app after every code change

With this, we aim to make the dev command platform aware, and make it so the web version uses .pth files and editable installs instead of .whl packages. By serving files directly into the browser via symlinks, developers will be able to make changes and see them reflected immediately upon refreshing the browser, which will help reduce wait times during development.

👍 A good summary of the overall problem and approach that will be taken.

1. dev venv

We'll need to set up a dedicated dev venv that contains only the pure Python modules we need to serve, like Toga modules, which we'll install as editable installs. The WebDevCommand will initialise a dedicated venv for the handling web dev mode(will implement a check if one exists and handling for users to force a refresh) in this venv we'll handle the installing of the application and its requirements as editable pip installs then upon launching read the .pth files and symlinks the reference packages into the projects www directory.

Possible clarification here: the app can't be installed as an "editable install", because it's not an installable package. The list of files and paths in the apps sources configuration will need to be included in the list of files being served by the app.

It would also be worth clarifying where this dev virtual environment will be created (as in - file system location) - I'd suggest .briefcase/dev-web-venv, with the .briefcase folder being added to the default project folder as an ignored folder.

Lastly, it's worth noting that at present, desktop "dev" mode doesn't perform editable installs at all. If the intention is to use editable installs for requirements specified as file path references, it may be necessary to make this change in such a way that desktop installs can also use this capability (i.e., if a requirement is specified as a path, dev installs that path as editable).

2. Third part libraries

3rd party libraries like 'numpy' and 'pandas' aren't pure Python. In the browser, Pyodide can't run these directly, so it requires .whl files. Pyodide micropip can dynamically fetch these WASM-compatible wheels at run time.

Yes - but that's not currently something Briefcase supports. Ideally it would, but it requires PEP 783 to be finalised, and for those changes to be reflected in pip.

3. Use of .pth files for dynamic source mapping

Editable installs create .pth files in the venv that act as a reference to the actual source folder on the machine. In dev mode, we'll configure the dev server to read these .pth files and dynamically serve the latest versions of the Python modules they reference. This means any changes to Toga's source code are available in the browser without needing a rebuild or copying of files, just a refresh

👍

4. Serving Toga Python modules to the browser for PyScript

To make Toga's Python modules available to PyScript in the browser, we'll serve them as standard .py files from our static assets directory. These files are loaded directly into the in-browser virtual filesystem described in PyScript Filesystem Guide, allowing PyScript to import and execute them as regular Python modules during runtime. This avoids the need for additional packaging steps

Which static assets folder is that? You're in dev mode - there isn't a static assets folder. dev mode can't assume anything from the briefcase create web template exists.

To be clear - its fine if dev mode isn't a 100% accurate representation of what happens in a fully built app - but you can't rely on the index.hml generated by briefcase create web as something that dev mode uses. This might mean duplicating some of the defaults from the web template as part of the dev command (or baking them into the dev web server).

Breakdown of tasks

The work can be mainly broken down into 3 parts

1. Enable Platform-aware dev commands
2. Get local Python files into the venv and serve them to the browser
3. Handle 3rd-party dependencies via Pyodide

These can all be further broken down into smaller subtasks, but this covers the general scope of work being done.

If this work can be broken down in to smaller parts, then that's an important part of the planning process. Going into this, we should have a clear understanding of the list of PRs that we're likely to see as a result of this work. It's OK if we deviate from that list for practical purposes discovered during development - but a delivery plan is part of any complex piece of work.

[mEp3ii2]

Possible clarification here: the app can't be installed as an "editable install", because it's not an installable package. The list of files and paths in the apps sources configuration will need to be included in the list of files being served by the app.

Thanks for the clarification. Bit of a miscommunication/poor wording on my part there.

It would also be worth clarifying where this dev virtual environment will be created (as in - file system location) - I'd suggest .briefcase/dev-web-venv, with the .briefcase folder being added to the default project folder as an ignored folder.

I'm happy to go with your suggestion of .briefcase/dev-web-venv

Lastly, it's worth noting that at present, desktop "dev" mode doesn't perform editable installs at all. If the intention is to use editable installs for requirements specified as file path references, it may be necessary to make this change in such a way that desktop installs can also use this capability (i.e., if a requirement is specified as a path, dev installs that path as editable).

That's a good point, I've only really been considering what we can do for the web. But this can be extended to also work with desktop installs

Yes - but that's not currently something Briefcase supports. Ideally it would, but it requires PEP 783 to be finalised, and for those changes to be reflected in pip.

I'm a little confused on this point as Briefcase FAQ mentions that for third-party Python packages, binary wheel support is currently limited to those provided by the pyodide project for web.
With Pyodide having a couple of different options for us to make use of to get imports
loadPackagesFromImports,find_imports, loadPackage.

Is there something that I'm missing here?

Which static assets folder is that? You're in dev mode - there isn't a static assets folder. dev mode can't assume anything from the briefcase create web template exists.

To be clear - its fine if dev mode isn't a 100% accurate representation of what happens in a fully built app - but you can't rely on the index.hml generated by briefcase create web as something that dev mode uses. This might mean duplicating some of the defaults from the web template as part of the dev command (or baking them into the dev web server).

Okay, so we can have briefcase dev web responsible for setting up the environment and generate a simple index.html and also create and managing a www/ directory to act as the static root file with this being contained in the .briefcase directory.

[freakboy3742]

Yes - but that's not currently something Briefcase supports. Ideally it would, but it requires PEP 783 to be finalised, and for those changes to be reflected in pip.

I'm a little confused on this point as Briefcase FAQ mentions that for third-party Python packages, binary wheel support is currently limited to those provided by the pyodide project for web. With Pyodide having a couple of different options for us to make use of to get imports loadPackagesFromImports,find_imports, loadPackage.

Is there something that I'm missing here?

If in doubt - try it.

Create a helloworld app, add astropy (a known binary package that Pyodide supports) to the requirements, and add import astropy. What happens?

Now take a look and see what wheels were added to the wheels folders. Notice anything?

To be clear - this is an area where the documentation is somewhere between ambiguous and wrong. It is possible to use binary wheels, but they must be supplied by pyodide... but that's the one source that Briefcase doesn't use at present, because it tries to build a list of static wheels, rather than dynamically loading them in the browser.

Is this fixable? Yes. Is it in scope for a dev web command? Arguable, given it's an issue that exists for run web as well. Would I be disappointed if you did fix this bug along the way? Not at all :-) Do I expect you to fix this bug in the context of a building dev web command? No.

Okay, so we can have briefcase dev web responsible for setting up the environment and generate a simple index.html and also create and managing a www/ directory to act as the static root file with this being contained in the .briefcase directory.

Yes - keeping in mind that this functionality will need to match what is described by #2283 (cc @caydnn / @kavi2du )

[mEp3ii2]

I think at this stage we can look at converting this into a proper ticket. Below is a draft including a roadmap that breaks down the tasks

Platform-Aware briefcase dev Command with Editable Installs for Web Development

What is the problem or limitation you are having?

Currently, briefcase dev is only supported on desktop platforms. For web backend, contributors must rebuild and repackage the entire project into wheels (e.g. `briefcase run web -r -u) even for minor changes. This process introduces significant wait times and slows down the speed of iteration for those developing Toga's web backend or debugging UI issues in the browser.

Describe the solution you'd like

We propose extending briefcase dev to support web development. The solution should:

Core Features

• Extend briefcase dev to be platform-aware and support web applications
• Use editable installs and .pth files instead of rebuilding .whl packages for pure Python modules
• Enable immediate code changes to be reflected in the browser with just a page refresh

Technical Implementation

1. Dedicated Dev Environment: Create a separate development virtual environment that contains only the pure Python modules needed for development
2. Editable Installs: Install the application and pure Python dependencies (like Toga modules) as editable pip installs in the dev venv
3. Dynamic Source Mapping: Use .pth files to reference actual source folders and serve the latest versions directly to the browser via symlinks
4. Static Asset Serving: Serve Toga Python modules as standard .py files to PyScript's in-browser virtual filesystem

Expected Outcome

• Immediate feedback when making code changes (refresh browser instead of rebuild)
• Faster development iteration cycles
• Seamless integration with the existing Briefcase workflow

Describe alternatives you've considered

Alternative 1: File Watching with Auto-Rebuild

• Implement a file watcher that automatically triggers rebuilds when source files change
• Limitation: Still requires the rebuild step, only automates it. Doesn't eliminate the wait time.

Alternative 2: Hybrid Approach with Partial Rebuilds

• Only rebuild changed modules instead of the entire application
• Limitation: Still involves a build step and doesn't provide the immediacy of serving source files directly.

The proposed solution with editable installs and .pth files is preferred because it:

• Leverages existing Python packaging mechanisms
• Provides the fastest possible feedback loop
• Maintains compatibility with the existing Briefcase architecture
• Allows for easy switching between dev and production modes

Additional Context

Technical Breakdown

The work can be broken down into two main components:

1. Enable Platform-aware dev commands - Modify the core briefcase dev command to detect and handle web platform differently
2. Local Python file serving - Implement the venv setup, editable installs, and .pth file reading to serve source files to the browser

Future Enhancements

The following features are planned as optional future iterations

1. Third-party dependency handling - Implement support for Pyodide's micropip and WASM-compatible wheels for libraries like numpy/pandas, this covers Web / Add Support for "Pyodide packages" #1103, and it should be noted that when PEP 783 is finalised, this should be revisited.
2. Hot reload functionality - Build upon the proposed solution to enable automatic browser refresh when code changes are detected, using CLI flags such as --live or --reload

Use Case

This enhancement is particularly valuable for developers working on:

• Toga-based web applications
• PyScript applications using Briefcase
• Any Python web app where frequent UI/logic iteration is required

References

• PyScript Filesystem Guide for in-browser virtual filesystem implementation

---

Roadmap of Changes: briefcase dev Support for Web

1. Dev-Mode Command & Venv Management

   • Implement briefcase dev web via a WebDevCommand subclass that respects platform and --test mode.
   • Auto-create or refresh the isolated .briefcase/dev-web-venv (with a --clean flag), using the same editable-install mechanism we'll share with desktop.

2. Unified Dev Environment & Asset Pipeline

   • Editable Installs
     • Install all pure-Python requirements in editable mode, generating .pth references.
   • Symlink & Serve
     • Parse each .pth file and symlink its source directory into the static root (.briefcase/www/), alongside an auto-generated index.html.
     • Launch a single static HTTP server to expose these assets.

3. Third-Party Package Support (Optional)

   • Serve pure-Python wheels over the same static server for micropip.install().
   • Optionally detect and micropip.loadPackage() known Pyodide-compatible binary packages, tracking any dynamic-only exceptions.

4. Live-Reload (Optional)

   • Add a --live/--reload flag to watch .py source files, re-bundle on change, and trigger an in-browser refresh.

5. Docs & Desktop Parity

   • Update the docs to document the new web workflow.
   • Evaluate extending editable install behavior to desktop briefcase dev.

[freakboy3742]

That looks great.

Some minor tweaks:

In the additional context - there is some (limited) crossover with existing tickets. For example, #1735 is a pre-existing ticket discussing standalone virtual environments; that issue might not be resolved by the changes you've proposed here, but there's at least some common themes. Cross linking means that when this code lands, anyone looking at #1735 will be able to see that some of the major technical issues have been resolved.

In the roadmap of changes:

Point 1 - is there any difference between --clean and -r? I'm not sure we need an additional flag for that.

Point 2 "Symlink and serve" - a project can contain multiple apps, so it may be necessary to differentiate the www (and, for that matter, the dev venv) on a per-app basis (so. - .briefcase/<app name>/www. I'm also not sure I see how you would be able to deliver .pth handling independent of the dev web server - those two feel sufficiently integrated that it's likely one PR.

Point 5 - docs - shouldn't exist. We won't land a PR unless all new features added by the PR are documented. Same goes for tests - we won't land "feature PR" and then "test PR" - it's one PR.

Otherwise - this looks good to go! Nice work!