portacode 1.3.32__py3-none-any.whl → 1.4.15.dev3__py3-none-any.whl

{portacode-1.3.32.dist-info → portacode-1.4.15.dev3.dist-info}/METADATA

@@ -1,11 +1,15 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.3.32
+Version: 1.4.15.dev3
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian
 Author-email: hi@menas.pro
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
@@ -24,6 +28,7 @@ Requires-Dist: watchdog>=3.0
 Requires-Dist: diff-match-patch>=20230430
 Requires-Dist: Pygments>=2.14.0
 Requires-Dist: ntplib>=0.4.0
+Requires-Dist: importlib_resources>=6.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
@@ -85,6 +90,33 @@ Once connected, you can:
 - Monitor system status
 - Access your development environment from any device
 
+Want to see Portacode running inside containers or powering classrooms? Browse the [`examples/` directory](https://github.com/portacode/portacode/tree/master/examples) (also bundled in the PyPI source) for copy-paste Docker Compose setups ranging from a single-device sandbox to a ten-seat workshop fleet.
+
+## 🔑 Pair Devices with Zero-Touch Codes
+
+The fastest way to bring a new machine online is with a short-lived pairing code:
+
+1. Log in to [https://portacode.com](https://portacode.com) and press **Pair Device** on the dashboard:  
+   ![Pair Device button](https://raw.githubusercontent.com/portacode/portacode/master/docs/images/pair-device-button.png)
+2. A four-digit code appears (valid for 15 minutes). This code only authorizes a pairing **request**—no device can reach your account until you approve it.
+3. On the device, run Portacode with the code:
+   ```bash
+   PORTACODE_PAIRING_CODE=1234 portacode connect \
+     --device-name "My Laptop" \
+     --project-path /srv/project-one \
+     --project-path /srv/project-two
+   ```
+   - `--device-name` (or `PORTACODE_DEVICE_NAME`) pre-fills the friendly label shown in the dashboard.
+   - Repeat `--project-path /abs/path` to register up to ten Projects automatically once the request is approved.
+   - Automating inside Docker? Export your own `PORTACODE_PROJECT_PATHS=/srv/a:/srv/b` and convert it into repeated `--project-path` switches before invoking the CLI—see `portacode_for_school/persistent_workspace/entrypoint.sh` for a reference implementation.
+4. Because the device has no fingerprint yet, the CLI bootstraps an in-memory keypair and announces a pending request to the dashboard. You immediately see the card with the supplied metadata:  
+   ![Pairing request card](https://raw.githubusercontent.com/portacode/portacode/master/docs/images/pairing-request.png)
+5. Click **Approve**. The CLI persists the keypair on disk and transitions into a normal authenticated connection. Future `portacode connect` runs reuse the stored RSA keys—no additional codes required unless you revoke the device.
+
+Need to pair multiple machines at once? A single pairing code can be reused concurrently: every device that launches `portacode connect` with that code shows up as its own approval card until you accept or decline it.
+
+This workflow works great for headless setups and containers: export the environment variables, run `portacode connect --non-interactive`, and finish the approval from the dashboard.
+
 ## 💡 Use Cases
 
 - **Remote Development**: Code, build, and debug from anywhere - even your phone
@@ -186,11 +218,47 @@ sudo apt-get install xclip
 ```
 
 ### Key Management
-Key files are stored in:
+Portacode follows the OS-specific *user data* directory (via [`platformdirs`](https://pypi.org/project/platformdirs/)) and keeps its identity in `portacode/keys/`:
 - **Linux**: `~/.local/share/portacode/keys/`
 - **macOS**: `~/Library/Application Support/portacode/keys/`
 - **Windows**: `%APPDATA%\portacode\keys\`
 
+When `PORTACODE_PAIRING_CODE` is set, the CLI generates an in-memory keypair, waits for dashboard approval, and only then writes the files to this directory. If that folder disappears, the CLI will create a fresh identity next time it runs.
+
+#### Persisting Keys in Containers
+Docker images (including the simple `python:3.11-slim` example that runs Portacode as `root`) store the data inside `/root/.local/share/portacode`. Bind-mount that path or override `XDG_DATA_HOME` so the keys survive container restarts:
+
+```yaml
+services:
+  device-01:
+    build: .
+    environment:
+      PORTACODE_PAIRING_CODE: "${PORTACODE_PAIRING_CODE:-}"
+    volumes:
+      - ./data/device-01/workspace:/root/workspace
+      - ./data/device-01/.local/share/portacode:/root/.local/share/portacode  # persists device keys
+```
+
+Alternatively, set `XDG_DATA_HOME=/root/.portacode` before running `portacode connect` and mount that directory from the host. The rule of thumb: **persist whichever folder contains `.local/share/portacode/keys/`** so your device fingerprint sticks around.
+
+#### Minimal Docker Example
+If you want a plug-and-play container, check the `examples/simple_device/` folder that ships with this repo and the PyPI source distribution. It contains a tiny `Dockerfile` and `docker-compose.yaml` you can copy as-is. The Dockerfile installs `git` before `pip install portacode` so GitPython can interact with repositories—remember to do the same in your own images if you expect to work inside version-controlled projects.
+
+The accompanying Compose file demonstrates how to:
+- run `portacode connect --non-interactive` with a predefined `--device-name` and `--project-path`
+- pass `PORTACODE_PAIRING_CODE` via environment variables
+- bind-mount your workspace plus `/root/.local/share/portacode` for key persistence
+
+Together, those 10 lines illustrate the complete flow for remotely accessing a Docker-hosted machine with Portacode.
+
+#### Workshop Fleet Example
+Training a group? `examples/workshop_fleet/` spins up ten identical containers—one per student—with their own workspace bind mounts plus a shared read-only `instructions/` folder. The Dockerfile in that folder copies everything from `initial_content/` into the image (`COPY initial_content/ /opt/initial_content/`), and the compose command seeds each student workspace on boot via `cp -an /opt/initial_content/. /root/workspace/`. That means:
+- Instructors drop starter code into `initial_content/` before `docker compose up` and every container gets the same seed files without overwriting student changes after the first sync.
+- The host `instructions/` directory is mounted at `/root/workspace/instructions` in **read-only** mode, so you can update agendas or hints live while students can only view them.
+- Each seat persists its Portacode identity in `data/student-XX/.local/share/portacode`, so reconnecting after a restart does not need new pairing codes.
+
+See the full walkthrough and assets in [`examples/workshop_fleet/`](https://github.com/portacode/portacode/tree/master/examples/workshop_fleet), which is also shipped inside the PyPI source tarball for offline access.
+
 ## 🌱 Early Stage Project
 
 **Portacode is a young project with big dreams.** We're building the future of remote development and mobile-first coding experiences. As a new project, we're actively seeking:
@@ -221,7 +289,7 @@ Check out our [GitHub repository](https://github.com/portacode/portacode) to get
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](https://github.com/portacode/portacode/blob/master/LICENSE) file for details.
 
 ---
 

portacode-1.4.15.dev3.dist-info/RECORD

@@ -0,0 +1,98 @@
+portacode/README.md,sha256=4dKtpvR8LNgZPVz37GmkQCMWIr_u25Ao63iW56s7Ke4,775
+portacode/__init__.py,sha256=oB3sV1wXr-um-RXio73UG8E5Xx6cF2ZVJveqjNmC-vQ,1086
+portacode/__main__.py,sha256=jmHTGC1hzmo9iKJLv-SSYe9BSIbPPZ2IOpecI03PlTs,296
+portacode/_version.py,sha256=1sfx8JK_QXWbIlvcX2Sn3XEnIw9YLhiiBq9EMvNgnss,719
+portacode/cli.py,sha256=mGLKoZ-T2FBF7IA9wUq0zyG0X9__-A1ao7gajjcVRH8,21828
+portacode/data.py,sha256=5-s291bv8J354myaHm1Y7CQZTZyRzMU3TGe5U4hb-FA,1591
+portacode/keypair.py,sha256=0OO4vHDcF1XMxCDqce61xFTlFwlTcmqe5HyGsXFEt7s,5838
+portacode/logging_categories.py,sha256=9m-BYrjyHh1vjZYBQT4JhAh6b_oYUhIWayO-noH1cSE,5063
+portacode/pairing.py,sha256=OzSuc0GhrknrDrny4aBU6IUnmKzRDTtocuDpyaVnyrs,3116
+portacode/service.py,sha256=p-HHMOAl20QsdcJydcZ74Iqes-wl8G8HItdSim30pUk,16537
+portacode/connection/README.md,sha256=f9rbuIEKa7cTm9C98rCiBbEtbiIXQU11esGSNhSMiJg,883
+portacode/connection/__init__.py,sha256=atqcVGkViIEd7pRa6cP2do07RJOM0UWpbnz5zXjGktU,250
+portacode/connection/client.py,sha256=jtLb9_YufqPkzi9t8VQH3iz_JEMisbtY6a8L9U5weiU,14181
+portacode/connection/multiplex.py,sha256=L-TxqJ_ZEbfNEfu1cwxgJ5vUdyRzZjsMy2Kx1diiZys,5237
+portacode/connection/terminal.py,sha256=oyLPOVLPlUuN_eRvHPGazB51yi8W8JEF3oOEYxucGTE,45069
+portacode/connection/handlers/README.md,sha256=HsLZG1QK1JNm67HsgL6WoDg9nxzKXxwkc5fJPFJdX5g,12169
+portacode/connection/handlers/WEBSOCKET_PROTOCOL.md,sha256=5VZSDPvXjtOl-8YZ-2UVtH8WgPnEWe7WB33YPrS8_8Q,104190
+portacode/connection/handlers/__init__.py,sha256=j69jGkf2-mYyCicvYfp2wk8-xB8yqpWktiN5xADXBno,3137
+portacode/connection/handlers/base.py,sha256=oENFb-Fcfzwk99Qx8gJQriEMiwSxwygwjOiuCH36hM4,10231
+portacode/connection/handlers/chunked_content.py,sha256=h6hXRmxSeOgnIxoU8CkmvEf2Odv-ajPrpHIe_W3GKcA,9251
+portacode/connection/handlers/diff_handlers.py,sha256=iYTIRCcpEQ03vIPKZCsMTE5aZbQw6sF04M3dM6rUV8Q,24477
+portacode/connection/handlers/file_handlers.py,sha256=nAJH8nXnX07xxD28ngLpgIUzcTuRwZBNpEGEKdRqohw,39507
+portacode/connection/handlers/project_aware_file_handlers.py,sha256=AqgMnDqX2893T2NsrvUSCwjN5VKj4Pb2TN0S_SuboOE,9803
+portacode/connection/handlers/project_state_handlers.py,sha256=v6ZefGW9i7n1aZLq2jOGumJIjYb6aHlPI4m1jkYewm8,1686
+portacode/connection/handlers/proxmox_infra.py,sha256=mH6xxT9v9X0jwdCBjU3p48lURYisY0T0HPjuzV3eoH8,76070
+portacode/connection/handlers/registry.py,sha256=qXGE60sYEWg6ZtVQzFcZ5YI2XWR6lMgw4hAL9x5qR1I,6181
+portacode/connection/handlers/session.py,sha256=uNGfiO_1B9-_yjJKkpvmbiJhIl6b-UXlT86UTfd6WYE,42219
+portacode/connection/handlers/system_handlers.py,sha256=fr12QpOr_Z8KYGUU-AYrTQwRPAcrLK85hvj3SEq1Kw8,14757
+portacode/connection/handlers/tab_factory.py,sha256=yn93h6GASjD1VpvW1oqpax3EpoT0r7r97zFXxML1wdA,16173
+portacode/connection/handlers/terminal_handlers.py,sha256=HRwHW1GiqG1NtHVEqXHKaYkFfQEzCDDH6YIlHcb4XD8,11866
+portacode/connection/handlers/test_proxmox_infra.py,sha256=d6iBB4pwAqWWdEGRayLxDEexqCElbGZDJlCB4bXba24,682
+portacode/connection/handlers/update_handler.py,sha256=f2K4LmG4sHJZ3LahzzoRtHBULTKkPUNwuyhwuAAg3RA,2054
+portacode/connection/handlers/project_state/README.md,sha256=trdd4ig6ungmwH5SpbSLfyxbL-QgPlGNU-_XrMEiXtw,10114
+portacode/connection/handlers/project_state/__init__.py,sha256=5ucIqk6Iclqg6bKkL8r_wVs5Tlt6B9J7yQH6yQUt7gc,2541
+portacode/connection/handlers/project_state/file_system_watcher.py,sha256=r9_UKxWTbzum0jGqxIafe68Ced2Y3xOp3ZmkpBOfRpw,8573
+portacode/connection/handlers/project_state/git_manager.py,sha256=iGQ7LYIA7uHsZHdj3HEc_LYo7S1Lqv6-AeyyMwknBPo,70027
+portacode/connection/handlers/project_state/handlers.py,sha256=qgOSt26rxAGNxW07AoevTwDPBdxblX4J-dX-EjOKtg4,38232
+portacode/connection/handlers/project_state/manager.py,sha256=pRMZqPOTK9YE3abNxiAbnERIJmRys673HFOEIBiKnm4,67184
+portacode/connection/handlers/project_state/models.py,sha256=EZTKvxHKs8QlQUbzI0u2IqfzfRRXZixUIDBwTGCJATI,4313
+portacode/connection/handlers/project_state/utils.py,sha256=LsbQr9TH9Bz30FqikmtTxco4PlB_n0kUIuPKQ6Fb_mo,1665
+portacode/link_capture/__init__.py,sha256=93LjyYDqzOimsIDBhsPibTl7tr-8DiIzyDF7JWQkE2A,1231
+portacode/link_capture/__pycache__/__init__.cpython-311.pyc,sha256=yKwOu63AoGpmk4l-jfGnt2G2YkI54I8MppgDvq8K4_s,2037
+portacode/link_capture/bin/elinks,sha256=VWEQlNcPazqaEJdDMbXmXJ2SLaAqN__IUBQNp8sSSto,104
+portacode/link_capture/bin/gio-open,sha256=jOYX5fCkqWfFAY6ebJt6C1UcXISHa4iRmLePs5jU3Ko,106
+portacode/link_capture/bin/gnome-open,sha256=oZHDhCtUWURmPry5EgkZjeJWZC2f10Qk101Dc4fNTVs,108
+portacode/link_capture/bin/gvfs-open,sha256=6lYC7RZJIQGwvGz7cCLPFkDTf29TNS3xuPJsSxR1kbs,107
+portacode/link_capture/bin/kde-open,sha256=9tz3N3horN_SCxl1sE8jAQ2OVy004Ebtl8llKz-mz70,106
+portacode/link_capture/bin/kfmclient,sha256=wkhcZdZFJ161Nua8mGZ-wtCAtzgLkqycR5Ait7Wus-g,107
+portacode/link_capture/bin/link_capture_exec.sh,sha256=bFyyuR7z7sEq-laOn9PLje5eoCLXNhgQvTrBLy3jKRg,234
+portacode/link_capture/bin/link_capture_wrapper.py,sha256=wvfCx2Urjzv5vNO1_58AAe4kKx2kVsmn9OoJwr6bnYI,2042
+portacode/link_capture/bin/links,sha256=BD3tioDtCXD-8KRcLEOaF53T4y9CWIZ8ANasDGy0mic,103
+portacode/link_capture/bin/links2,sha256=2tD7Iol-CyRJQdKs1VoNfRgaiui2mPsqcD9NolAr5_I,104
+portacode/link_capture/bin/lynx,sha256=FbiePbYRM1ozi1xP779ku05W2PwgKie_oRfj1KqrT3E,102
+portacode/link_capture/bin/mate-open,sha256=mL-sj3LVpzN-7Vj6gwFY8TMEG5kiRqyjwkdhMy5GRQQ,107
+portacode/link_capture/bin/netsurf,sha256=Z308xsqfJOwZGdsE3atZXdeJoGl1pAEzoaX4jSMPALg,105
+portacode/link_capture/bin/sensible-browser,sha256=oKVTZM1Z_mLEI2M-Lm-eaBK-Uqc00kwsa69qLhmx-kQ,114
+portacode/link_capture/bin/w3m,sha256=mdM0AF4h_ElkfI2YZ-Ko1KHgWk2zLQrRwb2w1QQxXU8,101
+portacode/link_capture/bin/x-www-browser,sha256=3RhqrunuuVktUf6WrbozW7qKlvfIlwXShl8PwF6Q80k,111
+portacode/link_capture/bin/xdg-open,sha256=GLUv5ejdN8tym4PNtgKqTcZpF7YHIO3BnlWs3z3SQ3U,106
+portacode/link_capture/bin/__pycache__/link_capture_wrapper.cpython-311.pyc,sha256=8NVUUJ1njsjCqZrZ2HPDmweauJQQ2W_9OWBC8Hi_o74,6049
+portacode/static/js/test-ntp-clock.html,sha256=bUow9sifIuLNPqKvuPbpQozmEE6RhdCI4Plib3CqUmw,2130
+portacode/static/js/utils/ntp-clock.js,sha256=t9moJyAGGU054BVtuGuSETVstlj1AoxVy44i4y9QWSs,6940
+portacode/utils/NTP_ARCHITECTURE.md,sha256=WkESTbz5SNAgdmDKk3DrHMhtYOPji_Kt3_a9arWdRig,3894
+portacode/utils/__init__.py,sha256=NgBlWTuNJESfIYJzP_3adI1yJQJR0XJLRpSdVNaBAN0,33
+portacode/utils/diff_apply.py,sha256=4Oi7ft3VUCKmiUE4VM-OeqO7Gk6H7PF3WnN4WHXtjxI,15157
+portacode/utils/diff_renderer.py,sha256=S76StnQ2DLfsz4Gg0m07UwPfRp8270PuzbNaQq-rmYk,13850
+portacode/utils/ntp_clock.py,sha256=VqCnWCTehCufE43W23oB-WUdAZGeCcLxkmIOPwInYHc,2499
+portacode-1.4.15.dev3.dist-info/licenses/LICENSE,sha256=2FGbCnUDgRYuQTkB1O1dUUpu5CVAjK1j4_p6ack9Z54,1066
+test_modules/README.md,sha256=Do_agkm9WhSzueXjRAkV_xEj6Emy5zB3N3VKY5Roce8,9274
+test_modules/__init__.py,sha256=1LcbHodIHsB0g-g4NGjSn6AMuCoGbymvXPYLOb6Z7F0,53
+test_modules/test_device_online.py,sha256=QtYq0Dq9vME8Gp2O4fGSheqVf8LUtpsSKosXXk56gGM,1654
+test_modules/test_file_operations.py,sha256=KXbh9t8Fah1jZp1pEPlU4_F06iJIJr2fR-yYc4RL6m8,38372
+test_modules/test_git_status_ui.py,sha256=A_qkt-0lFLwxdr7t6YQaM0HqUElDwlZi84mlngg11RA,18734
+test_modules/test_login_flow.py,sha256=LyKAgd6jkhO7cvy2zgGtAuUTgkD2G4otS_1hZ6O2jZo,1882
+test_modules/test_navigate_testing_folder.py,sha256=-1EXceUEwof_sYp5paMWUNT3mAv5aIpYJ65_vqFbZew,18233
+test_modules/test_play_store_screenshots.py,sha256=4t9EdB-BjIhAj2EA7yHchsiI3Z5bqmIGI26Dzebru2s,11094
+test_modules/test_terminal_buffer_performance.py,sha256=YQeDDZVnsQD3ug6udKUZH3NR7PHGP75uZsLZJYya7jg,12183
+test_modules/test_terminal_interaction.py,sha256=AxLb63oKhNLjKrny4hBj4hhFhrmHZ5UGStYDA0KzA0w,3163
+test_modules/test_terminal_loading_race_condition.py,sha256=PsGF8QzWeNNv6G7Fda6kETcBUcXyg_vRYeD-hDHAhCo,4158
+test_modules/test_terminal_start.py,sha256=y3IqG54UfMk-pAQ_fn5LuoM3kki6xRm11oB5AzfC-iE,1978
+testing_framework/.env.example,sha256=zGchLcB-p22YUUCU0JIyHLduLpDuFy8c5xPacctHvfY,708
+testing_framework/README.md,sha256=7o04mS2siNDuHA1UBh3Uu6XCbGomKjgb8gfl8YbClhE,9662
+testing_framework/__init__.py,sha256=safHXo_xBMwAwfiF_5rx0xGcPGfpBSOgkMZx04uj4No,575
+testing_framework/cli.py,sha256=ZHO37QO2IqZpC9VovrAYur2Vfc2AYeDqzi9Nb4lIA-w,13434
+testing_framework/requirements.txt,sha256=VeKSPyqS4MWwLhr0Upu7fImlXZQQjtL8uYeyHOjkYaE,249
+testing_framework/core/__init__.py,sha256=8AJQgqSCa9WgwkQNH_wTsA3JmJ4d4FRCweI-ioDgcNI,40
+testing_framework/core/base_test.py,sha256=0kKQDNCdAJyTQfJiMBzx9_2MMRrmaVfQF0cawhvian4,13149
+testing_framework/core/cli_manager.py,sha256=LDH_tWn-CmO08U_rmBIPpN_O6HLaQKRjdnfKGrtqs8Y,6991
+testing_framework/core/hierarchical_runner.py,sha256=tCeksh2cXbRspurSiE-mQM1M1BOPeY8mKFbjvaBTVHw,26401
+testing_framework/core/playwright_manager.py,sha256=Tw46qwxIhOFkS48C2IWIQHHNpEe-iI5MSPS2P7zZAmk,22249
+testing_framework/core/runner.py,sha256=j2QwNJmAxVBmJvcbVS7DgPJUKPNzqfLmt_4NNdaKmZU,19297
+testing_framework/core/shared_cli_manager.py,sha256=BESSNtyQb7BOlaOvZmm04T8Uezjms4KCBs2MzTxvzYQ,8790
+testing_framework/core/test_discovery.py,sha256=2FZ9fJ8Dp5dloA-fkgXoJ_gCMC_nYPBnA3Hs2xlagzM,4928
+portacode-1.4.15.dev3.dist-info/METADATA,sha256=fhua1K0pTVsxZaun0VkgDDpUBh5AdovF_z9U6_LyktE,13051
+portacode-1.4.15.dev3.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+portacode-1.4.15.dev3.dist-info/entry_points.txt,sha256=lLUUL-BM6_wwe44Xv0__5NQ1BnAz6jWjSMFvZdWW3zU,48
+portacode-1.4.15.dev3.dist-info/top_level.txt,sha256=TGhTYUxfW8SyVZc_zGgzjzc24gGT7nSw8Qf73liVRKM,41
+portacode-1.4.15.dev3.dist-info/RECORD,,

{portacode-1.3.32.dist-info → portacode-1.4.15.dev3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

test_modules/test_device_online.py

@@ -41,4 +41,4 @@ class DeviceOnlineTest(BaseTest):
     
     async def teardown(self):
         """Teardown for device online test."""
-        pass
+        pass

test_modules/test_login_flow.py

@@ -1,5 +1,7 @@
 """Login flow test - simplified and fast."""
 
+import os
+
 from testing_framework.core.base_test import BaseTest, TestResult, TestCategory
 
 
@@ -28,9 +30,11 @@ class LoginFlowTest(BaseTest):
         assert_that.status_ok(response, "Dashboard request")
         assert_that.url_contains(page, "/dashboard", "Dashboard URL")
         
-        # Verify we have active sessions
-        active_sessions = self.inspect().get_active_sessions()
-        assert_that.is_true(len(active_sessions) > 0, "Should have active sessions")
+        # Verify we have active sessions unless explicitly allowed to skip
+        allow_empty_sessions = os.getenv("ALLOW_EMPTY_SESSIONS", "false").lower() in ("1", "true", "yes")
+        if not allow_empty_sessions:
+            active_sessions = self.inspect().get_active_sessions()
+            assert_that.is_true(len(active_sessions) > 0, "Should have active sessions")
         
         if assert_that.has_failures():
             return TestResult(self.name, False, assert_that.get_failure_message())
@@ -43,4 +47,4 @@ class LoginFlowTest(BaseTest):
     
     async def teardown(self):
         """Teardown for login test."""
-        pass
+        pass

test_modules/test_play_store_screenshots.py

@@ -0,0 +1,294 @@
+"""Play Store screenshot tests for phone and tablet layouts."""
+
+import os
+from urllib.parse import urljoin
+
+from testing_framework.core.base_test import BaseTest, TestResult, TestCategory
+
+
+DEVICE_LABEL = os.getenv("PLAY_STORE_DEVICE_LABEL", "Workshop Seat 01")
+
+
+class PlayStoreScreenshotLogic:
+    """Shared workflow for capturing dashboard and editor screenshots."""
+
+    def __init__(self):
+        self.device_label = DEVICE_LABEL
+        self.device_name = os.getenv("SCREENSHOT_DEVICE_NAME", "default")
+        self.dashboard_zoom = float(os.getenv("SCREENSHOT_ZOOM", "1.0"))
+
+    async def apply_zoom(self, page):
+        if self.dashboard_zoom != 1.0:
+            percent = int(self.dashboard_zoom * 100)
+            await page.evaluate(
+                f"document.body.style.zoom='{percent}%'"
+            )
+
+    async def capture(self, test_instance, post_editor_steps=None) -> TestResult:
+        page = test_instance.playwright_manager.page
+        base_url = test_instance.playwright_manager.base_url
+
+        # Ensure dashboard is loaded
+        await page.goto(urljoin(base_url, "/dashboard/"))
+        await page.wait_for_load_state("networkidle")
+
+        # Locate specific device card and ensure it's online
+        device_card = (
+            page.locator(".device-card.online")
+            .filter(has_text=self.device_label)
+            .first
+        )
+        try:
+            await device_card.wait_for(timeout=10000)
+        except Exception:
+            return TestResult(
+                test_instance.name,
+                False,
+                f"Device '{self.device_label}' is not online or not visible",
+            )
+
+        # Scroll past navbar and capture dashboard screenshot
+        await page.evaluate("window.scrollTo(0, 66)")
+        await page.wait_for_timeout(500)
+        await test_instance.playwright_manager.take_screenshot(
+            f"{self.device_name}_dashboard"
+        )
+
+        # Open the editor from this device card
+        editor_button = device_card.get_by_text("Editor")
+        await editor_button.wait_for(timeout=5000)
+        await editor_button.scroll_into_view_if_needed()
+        await page.wait_for_timeout(200)
+        try:
+            await editor_button.click(force=True)
+        except Exception as exc:
+            return TestResult(
+                test_instance.name,
+                False,
+                f"Failed to open editor for {self.device_label}: {exc}",
+            )
+
+        # Select the first project in the modal
+        await page.wait_for_selector("#projectSelectorModal.show", timeout=10000)
+        await page.wait_for_selector(".item.project", timeout=10000)
+        first_project = page.locator(".item.project").first
+        await first_project.click()
+        await page.wait_for_selector(
+            "#projectSelectorModal.show",
+            state="hidden",
+            timeout=10000,
+        )
+
+        # Handle LitElement/Shadow DOM editor readiness
+        try:
+            await page.wait_for_selector("ace-editor", timeout=15000)
+            await page.wait_for_function(
+                """
+                () => {
+                    const el = document.querySelector('ace-editor');
+                    if (!el) return false;
+                    const shadow = el.shadowRoot;
+                    if (shadow && shadow.querySelector('.ace_editor')) return true;
+                    return !!el.querySelector('.ace_editor');
+                }
+                """,
+                timeout=20000,
+            )
+        except Exception:
+            test_instance.logger.warning(
+                "ACE editor shadow DOM not detected, proceeding with screenshot"
+            )
+
+        await page.wait_for_timeout(1000)
+        await test_instance.playwright_manager.take_screenshot(
+            f"{self.device_name}_editor"
+        )
+
+        if post_editor_steps:
+            result = await post_editor_steps(page, test_instance.playwright_manager)
+            if result:
+                return result
+
+        return TestResult(
+            test_instance.name,
+            True,
+            f"Screenshots captured for {self.device_name}",
+        )
+
+
+class PlayStorePhoneScreenshotTest(BaseTest):
+    """Capture phone-friendly screenshots for Play Store listing."""
+
+    def __init__(self):
+        self.logic = PlayStoreScreenshotLogic()
+        super().__init__(
+            name="play_store_phone_screenshot_test",
+            category=TestCategory.UI,
+            description="Capture phone-friendly screenshots for Play Store listing",
+            tags=["screenshots", "store", "phone"],
+            depends_on=["login_flow_test"],
+            start_url="/dashboard/",
+        )
+
+    async def setup(self):
+        await self.logic.apply_zoom(self.playwright_manager.page)
+
+    async def run(self) -> TestResult:
+        return await self.logic.capture(self, self._capture_phone_views)
+
+    async def teardown(self):
+        pass
+
+    async def _capture_phone_views(self, page, manager) -> TestResult:
+        async def take(name: str):
+            await page.wait_for_timeout(500)
+            await manager.take_screenshot(f"{self.logic.device_name}_{name}")
+
+        def locator_by_text(selector: str, text: str):
+            return page.locator(selector).filter(has_text=text).first
+
+        # Explorer tab
+        explorer_tab = locator_by_text(".mobile-nav-item", "Explorer")
+        try:
+            await explorer_tab.wait_for(timeout=5000)
+            await explorer_tab.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"Explorer tab not accessible: {exc}")
+        await take("explorer")
+
+        # Git status expansion
+        git_info = page.locator(".git-branch-info").first
+        try:
+            await git_info.wait_for(timeout=5000)
+            await git_info.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"Git status section unavailable: {exc}")
+        await take("git_status")
+
+        # Diff button
+        diff_btn = page.locator(".git-action-btn.diff").first
+        try:
+            await diff_btn.wait_for(timeout=5000)
+            await diff_btn.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"Diff action unavailable: {exc}")
+        await page.wait_for_timeout(1000)
+        await take("git_diff")
+
+        # Terminal tab
+        terminal_tab = locator_by_text(".mobile-nav-item", "Terminal")
+        try:
+            await terminal_tab.wait_for(timeout=5000)
+            await terminal_tab.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"Terminal tab not accessible: {exc}")
+        await take("terminal")
+
+        # AI Chat tab
+        ai_chat_tab = locator_by_text(".mobile-nav-item", "AI Chat")
+        try:
+            await ai_chat_tab.wait_for(timeout=5000)
+            await ai_chat_tab.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"AI Chat tab not accessible: {exc}")
+        await take("ai_chat")
+
+        # First chat item
+        chat_item = page.locator(".chat-item").first
+        try:
+            await chat_item.wait_for(timeout=5000)
+            await chat_item.click()
+        except Exception as exc:
+            return TestResult(self.name, False, f"No AI chat history available: {exc}")
+        await take("ai_chat_thread")
+
+        return TestResult(
+            self.name,
+            True,
+            "Phone screenshots captured across Explorer, Git, Diff, Terminal, and AI Chat",
+        )
+
+class PlayStoreTabletScreenshotTest(BaseTest):
+    """Capture tablet-friendly screenshots for Play Store listing."""
+
+    def __init__(self):
+        self.logic = PlayStoreScreenshotLogic()
+        super().__init__(
+            name="play_store_tablet_screenshot_test",
+            category=TestCategory.UI,
+            description="Capture tablet-friendly screenshots for Play Store listing",
+            tags=["screenshots", "store", "tablet"],
+            depends_on=["login_flow_test"],
+            start_url="/dashboard/",
+        )
+
+    async def setup(self):
+        await self.logic.apply_zoom(self.playwright_manager.page)
+
+    async def run(self) -> TestResult:
+        return await self.logic.capture(self, self._capture_tablet_views)
+
+    async def teardown(self):
+        pass
+
+    async def _capture_tablet_views(self, page, manager) -> TestResult:
+        async def click_and_wait(locator, description: str, screenshot_name: str = None):
+            try:
+                await locator.wait_for(timeout=5000)
+                await locator.click()
+            except Exception as exc:
+                return TestResult(self.name, False, f"Failed to interact with {description}: {exc}")
+            if screenshot_name:
+                await page.wait_for_timeout(500)
+                await manager.take_screenshot(f"{self.logic.device_name}_{screenshot_name}")
+            return None
+
+        # Helper locators
+        def divider_lid(title_text):
+            return page.locator(f'.divider-lid[title="Toggle {title_text}"]').first
+
+        def persistent_toggle(title_text):
+            return page.locator(
+                f'.persistent-toggle[title="Show {title_text}"], '
+                f'.persistent-toggle[title="Hide {title_text}"]'
+            ).first
+
+        # 1. Close terminal, expand git, open diff, capture
+        result = await click_and_wait(divider_lid("Terminal"), "Terminal divider")
+        if result:
+            return result
+        git_info = page.locator(".git-branch-info").first
+        result = await click_and_wait(git_info, "Git branch info", "git_status")
+        if result:
+            return result
+        git_diff_btn = page.locator(".git-action-btn.diff").first
+        result = await click_and_wait(git_diff_btn, "Git diff button", "git_version_control")
+        if result:
+            return result
+
+        # 2. Expand AI chat and open first chat
+        ai_chat_toggle = page.locator('.persistent-toggle.ai-chat-toggle')
+        result = await click_and_wait(ai_chat_toggle, "AI Chat toggle")
+        if result:
+            return result
+        chat_item = page.locator(".chat-item").first
+        result = await click_and_wait(chat_item, "AI chat conversation", "ai_chat_thread_tablet")
+        if result:
+            return result
+
+        # 3. Expand terminal, collapse file explorer, capture
+        terminal_tab = page.locator('.persistent-toggle.terminal-toggle-center')
+        result = await click_and_wait(terminal_tab, "Terminal toggle")
+        if result:
+            return result
+        explorer_divider = page.locator('.divider-lid.horizontal[title="Toggle File Explorer"]').first
+        result = await click_and_wait(explorer_divider, "Explorer divider", "terminal_focus")
+        if result:
+            return result
+
+        # 4. Collapse AI chat and expand file explorer to reset
+        return TestResult(
+            self.name,
+            True,
+            "Tablet screenshots captured across Git, diff, terminal, and AI chat views",
+        )

testing_framework/.env.example

@@ -15,4 +15,7 @@ TEST_HEADLESS=false    # true for headless mode, false for visible browser
 # Optional: Test Output Directories
 TEST_RESULTS_DIR=test_results
 TEST_RECORDINGS_DIR=test_recordings
-TEST_LOGS_DIR=test_results
+TEST_LOGS_DIR=test_results
+
+# Automation testing token (used by the testing framework to bypass captcha. Same token must be defined in ../main.env)
+TEST_RUNNER_BYPASS_TOKEN=same-as-in-main-env