Port Inkwitch game (production files) to ink-witch Space

Bring over the production app from gizzleon/hf-playground: app entry,
Space config, pinned requirements, and the witch_wood package (core,
engine, vision, gen, ui + custom HTML/JS frontend). Dev-only files
(tests, docs, uv.lock) are intentionally omitted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Local tooling / OS
+.claude/
+.vscode/
+.DS_Store
+
+# HF cache
+.cache/
+
+# Test artifacts
+.playwright-mcp/
+*.png

.python-version

@@ -0,0 +1 @@
+3.12

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,13 +1,23 @@
 ---
-title: Ink Witch
-emoji: 🐢
+title: Inkwitch
+emoji: 🧙‍♀️
 colorFrom: indigo
-colorTo: pink
+colorTo: purple
 sdk: gradio
-sdk_version: 6.17.3
+sdk_version: 6.16.0
 python_version: '3.12'
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Inkwitch
+
+Draw objects-on-demand for visitors under a stroke-length mana budget; a
+vision model (MiniCPM-V-4.6) judges each doodle against the requested object
+and its line-drawable properties. Earn stars to open harder, higher-paying
+slots and pay off your debt before the deadline.
+
+Runs on Hugging Face Spaces **ZeroGPU**: the model is loaded at startup and each
+appraisal runs inside a `@spaces.GPU` call.
+
+Local dev (no GPU): `WITCH_WOOD_MOCK=1 python app.py`

app.py

@@ -0,0 +1,8 @@
+from witch_wood.ui.server import app
+
+if __name__ == "__main__":
+    # ssr_mode=False is required: this Space serves a custom HTML/JS frontend
+    # from `@app.get("/")` + the /static mount. With SSR on (the default when
+    # Node is present, as it is on HF Spaces) Gradio's Node server takes over
+    # "/" and the custom Inkwitch page never renders.
+    app.launch(ssr_mode=False)

pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "ink-witch"
+version = "0.1.0"
+description = "Inkwitch — a doodle-judging game on Hugging Face ZeroGPU"
+readme = "README.md"
+# ZeroGPU runtimes only ship Python 3.12.12 and 3.10.13; pin to 3.12 so the
+# local venv matches the Space (README python_version: '3.12').
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    # gradio matches the Space's sdk_version in README.md frontmatter. The
+    # [oauth,mcp] extras mirror what the HF Spaces builder injects
+    # (`gradio[oauth,mcp]==<sdk_version>`); declaring them here makes uv resolve
+    # transitive pins (notably pydantic <=2.12.5, required by the mcp extra)
+    # that are compatible with the Space's own install command.
+    "gradio[oauth,mcp]==6.16.0",
+    # ZeroGPU supports torch up to 2.11.0 (not 2.12+); torchvision 0.26.0 is the
+    # matching sidecar for torch 2.11.x.
+    "torch==2.11.0",
+    "torchvision==0.26.0",
+    "transformers>=5.10.1",
+    "accelerate>=1.13.0",
+    # SDXL-Flash + scribble ControlNet image-gen second stage (witch_wood/gen).
+    "diffusers>=0.32.0",
+    "pillow>=12.0.0",
+    # Declared so uv co-resolves its transitive constraints (e.g. psutil). It is
+    # provided by the ZeroGPU base image and excluded from the exported
+    # requirements.txt — never pin `spaces` for the Space.
+    "spaces>=0.42.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,343 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --no-hashes --no-dev --no-emit-package spaces -o requirements.txt
+accelerate==1.13.0
+    # via hf-playground
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.13.0
+    # via
+    #   gradio
+    #   httpx
+    #   mcp
+    #   sse-starlette
+    #   starlette
+attrs==26.1.0
+    # via
+    #   jsonschema
+    #   referencing
+authlib==1.7.2
+    # via gradio
+brotli==1.2.0
+    # via gradio
+certifi==2026.5.20
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+cffi==2.0.0 ; platform_python_implementation != 'PyPy'
+    # via cryptography
+charset-normalizer==3.4.7
+    # via requests
+click==8.4.1
+    # via
+    #   huggingface-hub
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+cryptography==48.0.1
+    # via
+    #   authlib
+    #   joserfc
+    #   pyjwt
+cuda-bindings==13.3.1 ; sys_platform == 'linux'
+    # via torch
+cuda-pathfinder==1.5.5 ; sys_platform == 'linux'
+    # via cuda-bindings
+cuda-toolkit==13.0.2 ; sys_platform == 'linux'
+    # via torch
+diffusers==0.38.0
+    # via hf-playground
+fastapi==0.136.3
+    # via gradio
+filelock==3.29.2
+    # via
+    #   diffusers
+    #   huggingface-hub
+    #   torch
+fsspec==2026.4.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+    #   torch
+gradio==6.16.0
+    # via
+    #   hf-playground
+    #   spaces
+gradio-client==2.5.0
+    # via
+    #   gradio
+    #   hf-gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-gradio==0.4.1
+    # via gradio
+hf-xet==1.5.1 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   diffusers
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   safehttpx
+    #   spaces
+httpx-sse==0.4.3
+    # via mcp
+huggingface-hub==1.18.0
+    # via
+    #   accelerate
+    #   diffusers
+    #   gradio
+    #   gradio-client
+    #   tokenizers
+    #   transformers
+idna==3.18
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+importlib-metadata==9.0.0
+    # via diffusers
+itsdangerous==2.2.0
+    # via gradio
+jinja2==3.1.6
+    # via
+    #   gradio
+    #   torch
+joserfc==1.7.1
+    # via authlib
+jsonschema==4.26.0
+    # via mcp
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+mcp==1.27.2
+    # via gradio
+mdurl==0.1.2
+    # via markdown-it-py
+mpmath==1.3.0
+    # via sympy
+networkx==3.6.1
+    # via torch
+numpy==2.4.6
+    # via
+    #   accelerate
+    #   diffusers
+    #   gradio
+    #   pandas
+    #   torchvision
+    #   transformers
+nvidia-cublas==13.1.0.3 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cudnn-cu13
+    #   nvidia-cusolver
+nvidia-cuda-cupti==13.0.85 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cuda-nvrtc==13.0.88 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cuda-runtime==13.0.96 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cudnn-cu13==9.19.0.56 ; sys_platform == 'linux'
+    # via torch
+nvidia-cufft==12.0.0.61 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cufile==1.15.1.6 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-curand==10.4.0.35 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusolver==12.0.4.66 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusparse==12.6.3.3 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cusolver
+nvidia-cusparselt-cu13==0.8.0 ; sys_platform == 'linux'
+    # via torch
+nvidia-nccl-cu13==2.28.9 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvjitlink==13.0.88 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cufft
+    #   nvidia-cusolver
+    #   nvidia-cusparse
+nvidia-nvshmem-cu13==3.4.5 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvtx==13.0.85 ; sys_platform == 'linux'
+    # via cuda-toolkit
+orjson==3.11.9
+    # via gradio
+packaging==26.2
+    # via
+    #   accelerate
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   spaces
+    #   transformers
+pandas==3.0.3
+    # via gradio
+pillow==12.2.0
+    # via
+    #   diffusers
+    #   gradio
+    #   hf-playground
+    #   torchvision
+psutil==7.2.2
+    # via accelerate
+pycparser==3.0 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   fastapi
+    #   gradio
+    #   mcp
+    #   pydantic-settings
+    #   spaces
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.14.1
+    # via mcp
+pydub==0.25.1
+    # via gradio
+pygments==2.20.0
+    # via rich
+pyjwt==2.13.0
+    # via mcp
+python-dateutil==2.9.0.post0
+    # via pandas
+python-dotenv==1.2.2
+    # via pydantic-settings
+python-multipart==0.0.32
+    # via
+    #   gradio
+    #   mcp
+pytz==2026.2
+    # via gradio
+pywin32==312 ; sys_platform == 'win32'
+    # via mcp
+pyyaml==6.0.3
+    # via
+    #   accelerate
+    #   gradio
+    #   huggingface-hub
+    #   transformers
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+regex==2026.5.9
+    # via
+    #   diffusers
+    #   transformers
+requests==2.34.2
+    # via
+    #   diffusers
+    #   spaces
+rich==15.0.0
+    # via typer
+rpds-py==2026.5.1
+    # via
+    #   jsonschema
+    #   referencing
+safehttpx==0.1.7
+    # via gradio
+safetensors==0.8.0
+    # via
+    #   accelerate
+    #   diffusers
+    #   transformers
+semantic-version==2.10.0
+    # via gradio
+setuptools==81.0.0
+    # via torch
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+sse-starlette==3.4.4
+    # via mcp
+starlette==1.2.1
+    # via
+    #   fastapi
+    #   gradio
+    #   mcp
+    #   sse-starlette
+sympy==1.14.0
+    # via torch
+tokenizers==0.22.2
+    # via transformers
+tomlkit==0.14.0
+    # via gradio
+torch==2.11.0
+    # via
+    #   accelerate
+    #   hf-playground
+    #   torchvision
+torchvision==0.26.0
+    # via hf-playground
+tqdm==4.68.2
+    # via
+    #   huggingface-hub
+    #   transformers
+transformers==5.11.0
+    # via hf-playground
+triton==3.6.0 ; sys_platform == 'linux'
+    # via torch
+typer==0.25.1
+    # via
+    #   gradio
+    #   hf-gradio
+    #   huggingface-hub
+    #   transformers
+typing-extensions==4.15.0
+    # via
+    #   anyio
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   pydantic
+    #   pydantic-core
+    #   referencing
+    #   spaces
+    #   starlette
+    #   torch
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   mcp
+    #   pydantic
+    #   pydantic-settings
+tzdata==2026.2 ; sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+urllib3==2.7.0
+    # via requests
+uvicorn==0.49.0
+    # via
+    #   gradio
+    #   mcp
+zipp==4.1.0
+    # via importlib-metadata

witch_wood/core/constants.py

@@ -0,0 +1,80 @@
+"""All tunable game knobs in one place."""
+from __future__ import annotations
+
+import os
+
+# --- TEST MODE -------------------------------------------------------------
+# Manual-testing harness for the image-gen pipeline. Enable by setting the Space
+# Variable WITCH_WOOD_TESTMODE=1 (or the env var locally). When on, every new
+# game starts with effectively unlimited gold + mana, the visitor queue is the
+# FULL request pool (any object selectable, regardless of slot/tier/prereqs),
+# and a request may be delivered repeatedly. OFF by default — the real game is
+# unaffected. NOTHING here should ship enabled.
+TEST_MODE: bool = os.environ.get("WITCH_WOOD_TESTMODE") == "1"
+TEST_GOLD: int = 1_000_000
+TEST_MANA_MAX: int = 1_000_000
+
+# --- IMAGE GEN -------------------------------------------------------------
+# Single source of truth for the doodle->image stage (witch_wood/gen/scribble.py).
+# The server renders these into the tuning panel's HTML at serve time
+# (ui/server.py _render_index), so the panel defaults are never duplicated in the
+# static file; the panel can override any of them per-delivery. STYLE_SUFFIX /
+# BASE_NEGATIVE shape build_prompts(); the
+# numeric params drive generate_image(). Tuned for the 384px render: guidance 5.0
+# (7.5 over-cooks at low res, 2.5 is muddy), cnet 1.1 keeps doodle fidelity,
+# ~18 steps refines without oversaturating. ~5-9s/render.
+GEN_ENABLED: bool = True          # image-gen stage on by default
+GEN_STEPS: int = 30
+GEN_GUIDANCE: float = 5.0
+GEN_CNET_SCALE: float = 0.5
+GEN_SEED: int = -1  # -1 = random seed each generation
+STYLE_SUFFIX: str = (
+    ", full shot, realistic, photograph, soft even lighting, single subject, centered, plain simple background, minimal"
+)
+BASE_NEGATIVE: str = (
+    "lowres, closeup, blurry, graphic, painting, text, busy background, border, frame, lens flare, neon, rim light, cropped, partial object, zoom"
+)
+
+# Scoring thresholds (set from Gate B observations). With binary yes/no
+# confidences (yes->1.0/no->0.0) a 0.5 threshold is effectively a pass-through.
+T_RECOGNIZE: float = 0.5
+T_PROPERTY: float = 0.5
+
+# Payment model — fractions of a request's base_payment. Applied in
+# scoring.resolve(). Recognition is the make-or-break; properties are creative
+# upside. NEVER hard-code these in logic — they are balance knobs.
+RECOGNITION_FAIL_PAYOUT: float = 0.5   # flat payout when recognition fails (stars ignored)
+RECOGNITION_PASS_BASE: float = 1.0     # base payout when recognition passes
+STAR_BONUS_PER_STAR: float = 0.2       # added per property star earned, on a pass
+
+# Canvas reset: fraction of an abandoned drawing's spent mana refunded on Reset.
+CANVAS_RESET_REFUND: float = 0.7
+
+# Mana
+STARTING_MANA_MAX: int = 1500
+
+# Economy
+DEBT: int = 800
+DEADLINE_DAY: int = 5
+RENT: int = 30
+STARTING_GOLD: int = 30
+
+# Shop prices (slots are NOT sold — they unlock by stars, below)
+POTION_COST: int = 20
+POTION_COST_STEP: int = 10      # added to potion price per purchase that day; resets each morning
+POTION_MANA: int = 500          # temporary, today only
+MANA_UPGRADE_COST: int = 50
+MANA_UPGRADE_AMOUNT: int = 500  # permanent
+
+# Progression: slot index (1-based) -> lifetime total_stars required to open it.
+# Slot k offers a tier-(k-1) job (slot 1 = 0-star recognition-only ... slot 4 = 3-star).
+# Max tier is 3, so there are at most 4 slots. Slots 1 & 2 are free so the
+# 1-star slot can bootstrap star income.
+SLOT_UNLOCK_STARS: dict[int, int] = {1: 0, 2: 0, 3: 2, 4: 5}
+
+# Property appraisal mode. True -> one VLM generation per property (more
+# reliable when a request has several properties). False -> the legacy combined
+# numbered yes/no block in a single generation. The KV-cache on/off switch is
+# NOT here: it is a vision-layer concern (MiniCPMBackend(use_kv_cache=...)) so
+# caching can be removed without touching game knobs.
+SEPARATE_PROPERTY_CHECKS: bool = True

witch_wood/core/schema.py

@@ -0,0 +1,55 @@
+"""Core immutable game records."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Property:
+    label: str       # player-visible star label, e.g. "pointy"
+    predicate: str   # hidden VLM yes/no prompt, e.g. "the blade has a sharp pointed tip"
+
+
+@dataclass(frozen=True)
+class Prereq:
+    request_id: str
+    min_stars: int
+
+
+@dataclass(frozen=True)
+class Request:
+    id: str
+    visitor: str
+    flavor: str
+    object: str                      # recognition target
+    properties: tuple[Property, ...]
+    base_payment: int
+    requires: tuple["Prereq", ...] = ()   # storyline gates: each must be met
+    priority: int = 0                     # higher = surfaces first within its tier
+
+    @property
+    def tier(self) -> int:
+        return len(self.properties)
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """Raw, un-thresholded confidences in [0,1] from a VisionBackend.
+
+    Confidences are currently binary (yes->1.0 / no->0.0) from categorical
+    yes/no model queries. `description` is the model's free-form read of the
+    doodle (shown to the player for transparency/flavor; not scored).
+    """
+    recognition: float
+    properties: tuple[float, ...]    # aligned with Request.properties order
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class DeliverResult:
+    """Player-visible outcome of a delivery after thresholding."""
+    recognized: bool
+    stars: int
+    passes: tuple[bool, ...]
+    payment: int
+    description: str = ""   # the model's free-form read, shown to the player

witch_wood/core/state.py

@@ -0,0 +1,62 @@
+# witch_wood/core/state.py
+"""Mutable game state container + initial setup."""
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from witch_wood.core import constants as C
+from witch_wood.core.schema import Request
+from witch_wood.engine.content import REQUEST_POOL, sample_day
+from witch_wood.engine.progression import unlocked_slots
+
+
+@dataclass
+class GameState:
+    day: int
+    gold: int
+    mana: int
+    mana_max: int
+    slots: int                  # open slots (recomputed from total_stars each morning)
+    total_stars: int
+    debt: int
+    deadline_day: int
+    rent: int
+    status: str                 # "playing" | "won" | "lost" (terminal at deadline)
+    today: list[Request]
+    completed: tuple[str, ...]              # ids delivered TODAY (reset nightly)
+    stars_by_request: dict[str, int]        # lifetime best stars per request id
+    recognized: set[str]                    # ids that passed recognition at least once (gates storyline prereqs)
+    seen: set[str]                          # ids that have appeared on a guest list this session (retired whether or not served)
+    potions_bought_today: int               # potions bought today (drives escalating price; reset nightly)
+    rng: random.Random = field(repr=False)
+    logs: list[str] = field(default_factory=list)
+    test_mode: bool = False                 # per-session harness flag (unlimited gold/mana, full pool, repeat delivery)
+
+
+def new_game(seed: int = 0, test_mode: bool | None = None) -> GameState:
+    rng = random.Random(seed)
+    # Per-session override (hidden 5-reset gesture) falls back to the env constant.
+    tm = C.TEST_MODE if test_mode is None else test_mode
+    gold = C.TEST_GOLD if tm else C.STARTING_GOLD
+    mana_max = C.TEST_MANA_MAX if tm else C.STARTING_MANA_MAX
+    g = GameState(
+        day=1, gold=gold,
+        mana=mana_max, mana_max=mana_max,
+        slots=unlocked_slots(0), total_stars=0,
+        debt=C.DEBT, deadline_day=C.DEADLINE_DAY, rent=C.RENT,
+        status="playing",
+        today=[], completed=(), stars_by_request={}, recognized=set(), seen=set(),
+        potions_bought_today=0, rng=rng, test_mode=tm,
+    )
+    if tm:
+        # Test harness: expose the whole pool so any object can be drawn/tested,
+        # ignoring slot/tier/prereq gating. Repeat delivery is allowed in deliver().
+        g.today = list(REQUEST_POOL)
+        g.logs.append(
+            f"[TEST MODE] {len(g.today)} requests available; gold & mana unlimited."
+        )
+    else:
+        g.today = sample_day(g.total_stars, g.rng, g.stars_by_request, g.recognized, g.seen)
+        g.logs.append(f"Day 1: {len(g.today)} customers are waiting.")
+    return g

witch_wood/engine/content.py

@@ -0,0 +1,205 @@
+# witch_wood/engine/content.py
+"""Preset request pool, daily sampling, and the line-drawing content lint."""
+from __future__ import annotations
+
+import random
+
+from witch_wood.core.schema import Prereq, Property, Request
+from witch_wood.engine.progression import unlocked_slots
+
+# Attributes a monochrome line drawing CANNOT convey. Properties/predicates
+# must not depend on these — every star must be earnable by drawing alone.
+# (Decorative shape-based add-ons — a cat face, wings, a flower — are fine:
+# they are parts/shapes, not unseeable attributes, so they pass.)
+DISALLOWED_ATTRS: frozenset[str] = frozenset({
+    # colour
+    "red", "orange", "yellow", "green", "blue", "purple", "pink", "brown",
+    "black", "white", "grey", "gray", "colour", "color", "colored", "coloured",
+    # material / texture
+    "metallic", "metal", "wooden", "wood", "golden", "silver", "glass",
+    "furry", "fur", "fluffy", "smooth", "rough", "shiny", "glossy", "matte",
+    "transparent", "glowing",
+    # mass / temperature / other unseeable
+    "heavy", "light", "lightweight", "warm", "cold", "hot", "wet", "soft", "hard",
+})
+
+
+def lint_request(request: Request) -> None:
+    """Raise ValueError if any label/predicate references a disallowed attribute."""
+    for prop in request.properties:
+        text = f"{prop.label} {prop.predicate}".lower()
+        for word in DISALLOWED_ATTRS:
+            if word in text.split() or word in prop.label.lower().split("_"):
+                raise ValueError(
+                    f"Request {request.id!r} property {prop.label!r} uses "
+                    f"non-line-drawable attribute {word!r}: {prop.predicate!r}"
+                )
+
+
+def _p(label: str, predicate: str) -> Property:
+    return Property(label=label, predicate=predicate)
+
+
+# Preset pool. base_payment scales with tier. All predicates are line-inferable.
+# tier = number of properties (= max stars); the maximum tier is 3. Slot k draws
+# a tier-(k-1) request, so there are at most 4 slots (slot 1 = tier 0 ...
+# slot 4 = tier 3).
+#
+# Requests are grouped by STORYLINE first (a chain linked by `requires`), then the
+# standalone requests are grouped by tier. A storyline prerequisite must be
+# DELIVERED AND RECOGNISED; its `min_stars` then caps how many property stars that
+# recognised delivery needed (0 = recognition alone is enough).
+REQUEST_POOL: tuple[Request, ...] = (
+    # ══ Storyline: Pete & the war ══
+    # sword → shield → (the kingdom builds a) castle → Pete returns wounded (crutch)
+    Request("sword", "Pete", "A blade, witch! I will gladly bleed for the glory of our kingdom!",
+            "sword", (), 30, priority=2),
+    Request("shield", "Pete", "Help me defend the crown's honour!",
+            "shield", (_p("has_sigil", "there is a crab on the shield"),), 50,
+            priority=1, requires=(Prereq("sword", 0),)),
+    Request("castle", "Lucian", "A monument grand enough to celebrate my glorious triumph!",
+            "castle", (_p("has_towers", "there are towers"),
+                       _p("has_flag", "there is a flag on top"),
+                       _p("has_gate", "the castle has a gate/entrance")), 200,
+            priority=1, requires=(Prereq("sword", 0), Prereq("shield", 1))),
+    Request("crutch", "Pete", "Just something to lean on...",
+            "crutch", (), 10, priority=1, requires=(Prereq("castle", 0),)),
+
+    # ══ Storyline: James & Della's wedding ══
+    # comb (James' gift) + wristwatch (Della's gift) → wedding_cake (their big day)
+    Request("wristwatch", "Della", "A gift for my boyfriend so he won't keep me waiting next time!",
+            "wristwatch", (_p("has_strap", "there is a watch strap"),
+                           _p("has_clock_hands", "the watch has clock hands")), 40,
+            priority=1),
+    Request("comb", "James", "A secret gift for my girl. I want her to look beautiful when I ask the big question.",
+            "comb", (), 15, priority=1, requires=(Prereq("wristwatch", 1),)),
+    Request("wedding_cake", "James & Della", "Our big day is finally here!",
+            "wedding cake", (_p("has_tiers", "there are stacked tiers"),
+                     _p("has_topper", "there is a heart on top"),
+                     _p("has_decorations", "there are decorative swirls or dots")), 170,
+            requires=(Prereq("comb", 0), Prereq("wristwatch", 0)), priority=1),
+
+    # ══ Standalone — tier 0: recognition-only (no properties) ══
+    # Request("bread", "Gary", "Please, my kids haven't eaten a hot meal in two days.",
+    #         "bread", (), 15),
+    Request("carrot", "Olaf", "The forest rabbits stole my nose while I was sleeping!",
+            "carrot", (), 15),
+    Request("tent", "Johan", "Can't wait for my next camping!",
+            "tent", (), 20),
+    Request("garlic", "Oliver", "I need something to hang by my front door. I saw glowing eyes outside last night!",
+            "garlic", (), 20),
+    Request("lollipop", "Rado", "Could you make something sweet? My little sister won't stop crying...",
+            "lollipop", (), 15),
+
+    # ══ Standalone — tier 1 ══
+    Request("pants", "Rex", "I can't go to town looking like this! I need a new pair!",
+            "pants", (_p("has_pocket", "the pants have pockets"),), 30),
+    Request("candle", "Kota", "The night is so long, and the darkness feels heavy without it.",
+            "candle", (_p("has_flame", "there is a flame on top"),), 24),
+    Request("fish", "Kitty", "Meow~",
+            "fish", (_p("has_fin", "there is at least one fin"),), 20),
+    Request("briefcase", "Anna", "It's my first day of work tomorrow!",
+            "briefcase", (_p("has_handle", "it has a handle"),), 30),
+    Request("dress", "Ella", "My sisters left me behind, but I must attend the ball!",
+            "dress", (_p("has_flower", "there are flower patterns on the dress"),), 30),
+
+    # ══ Standalone — tier 2 ══
+    Request("apple", "Melanion", "I must win her, no matter the cost!",
+            "apple", (_p("has_stem", "there is a small stem on top"),
+                      _p("has_leaf", "there is a leaf by the stem")), 100),
+    Request("boat", "Robinson", "Time to sail back home.",
+            "boat", (_p("has_mast", "there is a vertical mast"),
+                     _p("has_sail", "there is a triangular sail")), 80),
+    Request("cat_mug", "Michelle", "A cute mug to cheer my mornings!",
+            "mug", (_p("has_handle", "there is a handle on the side"),
+                    _p("cat_face", "there is a cat face drawn on it")), 50),
+    Request("key", "Ivan", "Hopefully this one follows me well and I won't lose it again!",
+            "key", (_p("has_bow", "there is a round loop at one end"),
+                    _p("has_wings", "the key has wings around the bow")), 80),
+    Request("teddy_bear", "Dave", "I want a new friend!",
+            "teddy bear", (_p("has_body", "the teddy bear has a body"),
+                           _p("has_bow_tie", "there is a bow tie around the neck")), 60),
+
+    # ══ Standalone — tier 3 ══
+    Request("christmas_tree", "Ethan", "I want the most fabulous Christmas tree in town!",
+            "Christmas tree", (_p("has_boxes", "there are gift boxes beneath the tree."),
+                     _p("has_decorations", "there are decorative balls on the tree"),
+                     _p("has_star", "there is a star on top")), 120),
+    Request("house", "Ben", "We've been wandering the wild roads for so long.",
+            "house", (_p("has_roof", "there is a triangular roof"),
+                      _p("has_window", "there is a window"),
+                      _p("has_door", "there is a door")), 120),
+    Request("teapot", "Delilah", "The high duchess is coming for my tea reception, and everything must be perfect!",
+            "teapot", (_p("has_handle", "there is a handle on the side"),
+                       _p("has_lid", "there is a lid on top"),
+                       _p("has_leaf", "there is a leaf drawn on it")), 100),
+)
+
+
+def validate_pool() -> None:
+    """Lint every request; verify every `requires` references an existing id."""
+    ids = {r.id for r in REQUEST_POOL}
+    for request in REQUEST_POOL:
+        lint_request(request)
+        for prereq in request.requires:
+            if prereq.request_id not in ids:
+                raise ValueError(
+                    f"Request {request.id!r} requires unknown id {prereq.request_id!r}"
+                )
+
+
+def available_requests(
+    stars_by_request: dict[str, int],
+    recognized: set[str] | None = None,
+    seen: set[str] | None = None,
+) -> list[Request]:
+    """Requests eligible by STORYLINE rules (tier-agnostic): prerequisites met
+    AND not yet delivered AND not yet shown this session (once-per-session).
+
+    `stars_by_request` is the lifetime best stars per delivered request id (key
+    present == delivered at least once, pass or fail). `recognized` is the set of
+    ids whose delivery PASSED recognition. A prerequisite is met only when it was
+    delivered AND recognised; `min_stars` then caps how many property stars that
+    recognised delivery needed (0 = recognition alone). `seen` is the set of ids
+    that have already appeared on a guest list this session: a guest who was shown
+    but never served is retired too, so they never re-appear. Slot/tier gating is
+    applied separately in `sample_day`."""
+    recognized = recognized or set()
+    seen = seen or set()
+
+    def prereq_met(p: Prereq) -> bool:
+        return (
+            p.request_id in recognized
+            and stars_by_request.get(p.request_id, 0) >= p.min_stars
+        )
+
+    def ok(r: Request) -> bool:
+        if r.id in stars_by_request or r.id in seen:   # retired: delivered OR already shown
+            return False
+        return all(prereq_met(p) for p in r.requires)
+
+    return [r for r in REQUEST_POOL if ok(r)]
+
+
+def sample_day(
+    total_stars: int,
+    rng: random.Random,
+    stars_by_request: dict[str, int] | None = None,
+    recognized: set[str] | None = None,
+    seen: set[str] | None = None,
+) -> list[Request]:
+    """Fill the open slots. Slot k (1..unlocked_slots) draws one eligible
+    tier-(k-1) request; a slot with no eligible request is left empty."""
+    avail = available_requests(stars_by_request or {}, recognized or set(), seen or set())
+    day: list[Request] = []
+    chosen: set[str] = set()
+    for slot in range(1, unlocked_slots(total_stars) + 1):
+        tier = slot - 1
+        pool = [r for r in avail if r.tier == tier and r.id not in chosen]
+        if pool:
+            top = max(r.priority for r in pool)          # highest non-empty priority group
+            group = [r for r in pool if r.priority == top]
+            pick = rng.choice(group)
+            day.append(pick)
+            chosen.add(pick.id)
+    return day

witch_wood/engine/economy.py

@@ -0,0 +1,77 @@
+# witch_wood/engine/economy.py
+"""Pure-ish mutations: shop purchases, nightfall, win/lose. Operate on GameState."""
+from __future__ import annotations
+
+from witch_wood.core import constants as C
+from witch_wood.core.state import GameState
+
+
+def _spend(g: GameState, cost: int) -> None:
+    if g.gold < cost:
+        raise ValueError(f"not enough gold: need {cost}, have {g.gold}")
+    g.gold -= cost
+
+
+def current_potion_price(g: GameState) -> int:
+    """Today's next-potion price: base plus a step per potion already bought."""
+    return C.POTION_COST + C.POTION_COST_STEP * g.potions_bought_today
+
+
+def buy_potion(g: GameState) -> None:
+    price = current_potion_price(g)
+    _spend(g, price)
+    g.mana += C.POTION_MANA           # temporary; cleared at next morning refill
+    g.potions_bought_today += 1       # next potion today costs one step more
+    g.logs.append(f"Bought a Mana Potion for {price}g. Mana increased by {C.POTION_MANA}.")
+
+
+def buy_mana_upgrade(g: GameState) -> None:
+    _spend(g, C.MANA_UPGRADE_COST)
+    g.mana_max += C.MANA_UPGRADE_AMOUNT
+    g.logs.append(f"Crystal upgraded for {C.MANA_UPGRADE_COST}g. Max Mana increased by {C.MANA_UPGRADE_AMOUNT}.")
+
+
+from witch_wood.engine.content import sample_day
+from witch_wood.engine.progression import unlocked_slots
+
+
+def _advance_morning(g: GameState) -> None:
+    g.day += 1
+    g.mana = g.mana_max                       # refill; discards potion overflow
+    g.slots = unlocked_slots(g.total_stars)   # newly-earned slots open this morning
+    if not g.test_mode:
+        # Retire everyone who appeared today: an unserved guest does NOT re-appear
+        # later this session (served ones are already retired via stars_by_request).
+        g.seen.update(r.id for r in g.today)
+    g.today = sample_day(g.total_stars, g.rng, g.stars_by_request, g.recognized, g.seen)
+    g.completed = ()
+    g.potions_bought_today = 0                # potion price resets each morning
+    g.logs.append(f"Day {g.day}: {len(g.today)} customers are waiting.")
+
+
+def end_day(g: GameState) -> None:
+    """Pay rent, then resolve the deadline. The run ENDS at the deadline."""
+    # 1) Rent first — failing rent is an immediate loss.
+    if g.gold < g.rent:
+        g.status = "lost"
+        g.logs.append(f"Failed to pay rent of {g.rent}g.")
+        return
+    
+    rent_paid = g.rent
+    g.gold -= g.rent
+    g.logs.append(f"Paid {rent_paid}g in rent.")
+
+    # 2) Deadline: collect the debt in full -> win or lose, then STOP (no new day).
+    if g.day >= g.deadline_day:
+        if g.gold >= g.debt:
+            g.gold -= g.debt
+            g.logs.append(f"Paid the remaining debt of {g.debt}g.")
+            g.debt = 0
+            g.status = "won"
+        else:
+            g.status = "lost"
+            g.logs.append(f"Failed to pay the debt of {g.debt}g.")
+        return
+
+    # 3) Otherwise advance to the next morning.
+    _advance_morning(g)

witch_wood/engine/game.py

@@ -0,0 +1,123 @@
+# witch_wood/engine/game.py
+"""Orchestrates a delivery against GameState using a VisionBackend."""
+from __future__ import annotations
+
+from witch_wood.core import constants as C
+from witch_wood.core.schema import DeliverResult, Request, Verdict
+from witch_wood.core.state import GameState
+from witch_wood.engine import scoring
+from witch_wood.engine.content import available_requests
+from witch_wood.engine.progression import unlocked_slots
+from witch_wood.vision.base import VisionBackend
+
+
+def _find_request(g: GameState, request_id: str) -> Request:
+    for r in g.today:
+        if r.id == request_id:
+            return r
+    raise ValueError(f"no such request today: {request_id!r}")
+
+
+def deliver(
+    g: GameState,
+    request_id: str,
+    image,
+    spent_length: int,
+    backend: VisionBackend | None = None,
+    gen=None,
+    gpu_pipeline=None,
+) -> tuple[DeliverResult, object | None]:
+    """Resolve a delivery. Returns (result, render).
+
+    Pipeline (conceptually):
+      1. Appraise the DOODLE — recognition (gate) + per-property checks.
+      2. If recognition passes, generate a polished image (the prompt injects the
+         object AND the doodle's passed/failed properties, so the generator is
+         told what to draw).
+      3. Re-check the properties on that RENDER and score from those — stars
+         reflect what's actually shown, catching properties the generator dropped.
+         Doodle-PASSED properties are trusted (scored as-is) so the player isn't
+         punished when the generator quietly drops a feature they drew; only
+         doodle-FAILED ones are re-asked on the render.
+
+    Two execution paths produce the (verdict, render) pair:
+      * `gpu_pipeline` (real Space): all three steps run in ONE @spaces.GPU
+        acquisition; `gpu_pipeline(image, request) -> (verdict, render)` and the
+        returned verdict already reflects the render re-check.
+      * split path (MOCK / tests / no-GPU): `backend.appraise` then, if `gen` is
+        given, `gen(image, request, doodle_passes) -> render` and
+        `backend.check_properties` re-checks the render.
+    If neither produces a render (gen disabled, recognition fails, or generation
+    fails), scoring falls back to the doodle's own property checks.
+    """
+    if request_id in g.completed and not g.test_mode:
+        raise ValueError(f"request {request_id!r} already delivered")
+    if spent_length > g.mana:
+        raise ValueError(f"not enough mana: spent {spent_length}, have {g.mana}")
+    request = _find_request(g, request_id)
+
+    g.mana -= spent_length                         # ink is spent regardless of verdict
+
+    if gpu_pipeline is not None:
+        # Fused fast path: one GPU acquisition for appraise + image-gen + render
+        # re-check. The verdict already incorporates the render re-check.
+        verdict, render = gpu_pipeline(image, request)
+    else:
+        verdict = backend.appraise(image, request)  # recognition + doodle properties
+        render = None
+        if gen is not None and verdict.recognition >= C.T_RECOGNIZE:
+            doodle_passes = tuple(c >= C.T_PROPERTY for c in verdict.properties)
+            render = gen(image, request, doodle_passes)
+            if render is not None and request.properties:
+                # Score the RENDER, not the doodle: stars reflect the shown image.
+                render_props = backend.check_properties(render, request)
+                verdict = Verdict(verdict.recognition, render_props, verdict.description)
+
+    result = scoring.resolve(verdict, request)
+
+    g.gold += result.payment
+    g.total_stars += result.stars
+    g.completed = (*g.completed, request_id)
+    # Lifetime best stars per request (key always created — even at 0 stars —
+    # so once-per-session retirement works; see content.available_requests).
+    g.stars_by_request[request_id] = max(
+        g.stars_by_request.get(request_id, 0), result.stars
+    )
+    # Recognition is what gates storyline prerequisites (a delivery that failed
+    # recognition banks 0 stars but must NOT satisfy a min_stars=0 prereq).
+    if result.recognized:
+        g.recognized.add(request_id)
+
+    if result.recognized:
+        g.logs.append(f"Successfully transmuted the {request.object}! Received {result.payment}g.")
+    else:
+        g.logs.append(f"Failed to transmute the {request.object}. Received {result.payment}g.")
+
+    # Recompute slots and sample a request for each newly opened slot immediately
+    old_slots = g.slots
+    new_slots = unlocked_slots(g.total_stars)
+    if new_slots > old_slots:
+        g.slots = new_slots
+        avail = available_requests(g.stars_by_request, g.recognized, g.seen)
+        chosen = {r.id for r in g.today}
+        for slot in range(old_slots + 1, new_slots + 1):
+            tier = slot - 1
+            pool = [r for r in avail if r.tier == tier and r.id not in chosen]
+            if pool:
+                top = max(r.priority for r in pool)
+                group = [r for r in pool if r.priority == top]
+                pick = g.rng.choice(group)
+                g.today.append(pick)
+                chosen.add(pick.id)
+                g.logs.append(f"New customer {pick.visitor} is coming.")
+
+    return result, render
+
+
+def reset_drawing(g: GameState, spent_length: int) -> int:
+    """Abandon the in-progress (undelivered) drawing. Refund
+    `CANVAS_RESET_REFUND` of its spent ink; charge only the remainder against
+    the day's mana. Returns the new remaining mana (re-arms the canvas budget)."""
+    penalty = round((1 - C.CANVAS_RESET_REFUND) * spent_length)
+    g.mana = max(0, g.mana - penalty)
+    return g.mana

witch_wood/engine/progression.py

@@ -0,0 +1,10 @@
+# witch_wood/engine/progression.py
+"""Lifetime total_stars -> number of open slots (slot k offers tier k-1)."""
+from __future__ import annotations
+
+from witch_wood.core import constants as C
+
+
+def unlocked_slots(total_stars: int) -> int:
+    """How many slots are open. Slot k (1-based) presents a tier-(k-1) job."""
+    return sum(1 for need in C.SLOT_UNLOCK_STARS.values() if total_stars >= need)

witch_wood/engine/scoring.py

@@ -0,0 +1,36 @@
+# witch_wood/engine/scoring.py
+"""Turn a raw Verdict into a player-visible DeliverResult.
+
+Payment model (all fractions are tunable constants — never hard-coded here):
+- recognition FAILS -> flat `RECOGNITION_FAIL_PAYOUT` of base, stars ignored.
+- recognition PASSES -> `RECOGNITION_PASS_BASE + STAR_BONUS_PER_STAR * stars` of base.
+"""
+from __future__ import annotations
+
+from witch_wood.core import constants as C
+from witch_wood.core.schema import DeliverResult, Request, Verdict
+
+
+def resolve(
+    verdict: Verdict,
+    request: Request,
+    t_recognize: float = C.T_RECOGNIZE,
+    t_property: float = C.T_PROPERTY,
+) -> DeliverResult:
+    total = len(request.properties)
+    recognized = verdict.recognition >= t_recognize
+    if not recognized:
+        payment = round(request.base_payment * C.RECOGNITION_FAIL_PAYOUT)
+        return DeliverResult(
+            recognized=False, stars=0,
+            passes=tuple(False for _ in range(total)), payment=payment,
+            description=verdict.description,
+        )
+    passes = tuple(conf >= t_property for conf in verdict.properties)
+    stars = sum(passes)
+    frac = C.RECOGNITION_PASS_BASE + C.STAR_BONUS_PER_STAR * stars
+    payment = round(request.base_payment * frac)
+    return DeliverResult(
+        recognized=True, stars=stars, passes=passes, payment=payment,
+        description=verdict.description,
+    )

witch_wood/gen/pipeline.py

@@ -0,0 +1,84 @@
+"""Fused delivery pipeline: appraise + image-gen + render re-check in ONE
+`@spaces.GPU` acquisition.
+
+Each delivery used to make three separate ZeroGPU entries (doodle appraisal,
+diffusion, render re-check), each paying its own queue wait + worker attach +
+weight streaming. Both heavy models (MiniCPM-V and the SDXL-Flash pipe) are
+module-global and eagerly loaded at Space startup, so a single decorated
+function can drive both and return a plain `(Verdict, PIL.Image | None)` — both
+picklable, no CUDA tensors crossing the worker boundary.
+
+The split path (separate calls) still exists for MOCK / tests / CUDA-less dev;
+this module is imported only on the real GPU Space (see ui/server.py).
+"""
+from __future__ import annotations
+
+import spaces
+
+from witch_wood.core import constants as C
+from witch_wood.core.schema import Request, Verdict
+from witch_wood.gen import scribble
+from witch_wood.vision import minicpm
+
+
+def _duration(image, request: Request, gen_opts: dict) -> int:
+    """GPU seconds reserved for the quota pre-check, CAPPED at 30s.
+
+    The cap is the point: the anonymous/free ZeroGPU tier has a per-call duration
+    limit, and declaring more fails with 'ZeroGPU illegal duration' — locking
+    logged-out visitors out entirely. 30s keeps every delivery within that tier
+    so anyone can play. It's also comfortable on compute: the Phase-1 benchmark
+    measured ~4.4s warm for a 3-property delivery (appraise ~2.6 + gen ~1.8 +
+    recheck, which the skip-passed opt often elides); both models are eager-loaded
+    at Space startup so workers are usually warm, leaving headroom under 30s for
+    cold weight-streaming. Lighter deliveries reserve less (shorter durations rank
+    higher in the queue)."""
+    n = len(request.properties)
+    if not gen_opts.get("enabled"):
+        return min(30, 18 + 2 * n)
+    return 30
+
+
+@spaces.GPU(duration=_duration)
+def run_delivery_gpu(image, request: Request, gen_opts: dict):
+    """Appraise the doodle, optionally render it, re-check the render — all in
+    one GPU call. Returns `(verdict, render)` where `verdict` already reflects
+    the render re-check when a render was produced.
+
+    `gen_opts` is the tuning-panel payload (`_gen_options`): {enabled, steps,
+    guidance, controlnet_scale, seed, style_suffix, base_negative}. When
+    `enabled` is false (or recognition fails) only the appraisal runs and the
+    render is `None` — scoring falls back to the doodle, exactly as a no-gen
+    delivery does today."""
+    model, processor = minicpm._ensure_loaded()
+    verdict = minicpm._appraise(model, processor, image, request, use_kv_cache=True)
+
+    render = None
+    if gen_opts.get("enabled") and verdict.recognition >= C.T_RECOGNIZE:
+        passes = tuple(c >= C.T_PROPERTY for c in verdict.properties)
+        try:
+            prompt, negative = scribble.build_prompts(
+                request.object, request.properties, passes,
+                gen_opts["style_suffix"], gen_opts["base_negative"],
+            )
+            print(f"[image-gen] {request.id}: doodle_passes={passes}\n"
+                  f"  prompt  = {prompt!r}\n"
+                  f"  negative= {negative!r}", flush=True)
+            render = scribble._generate(
+                scribble._ensure_loaded(), image, prompt, negative,
+                gen_opts["steps"], gen_opts["guidance"],
+                gen_opts["controlnet_scale"], gen_opts["seed"],
+            )
+        except Exception as gen_err:  # noqa: BLE001 — fall back to the doodle verdict
+            print(f"[image-gen] generation failed: {gen_err}", flush=True)
+            render = None
+
+        if render is not None and request.properties:
+            # Re-check only the doodle-failed props on the render; passed props
+            # are trusted to carry through (scored 1.0). See _check_properties.
+            render_props = minicpm._check_properties(
+                model, processor, render, request, passes
+            )
+            verdict = Verdict(verdict.recognition, render_props, verdict.description)
+
+    return verdict, render

witch_wood/gen/scribble.py

@@ -0,0 +1,173 @@
+"""Scribble -> polished image generator (ZeroGPU-ready).
+
+Second GPU stage of a delivery: once MiniCPM-V passes recognition, the player's
+doodle is turned into a polished image by a ControlNet (xinsir scribble-sdxl)
+on top of the few-step SDXL-Flash backbone. The doodle drives the ControlNet;
+the *text* prompt is built from the per-property pass/fail result (NOT from
+MiniCPM's free-form description) — passed predicates steer the positive prompt,
+failed ones the negative prompt (see `build_prompts`).
+
+Ported from the `experimental/image-gen-spike` branch
+(`scripts/scribble_gen_spike.py`), adapted for ZeroGPU:
+
+  * The pipe is loaded ONCE at module scope (registered for ZeroGPU device
+    migration); the real GPU is only attached inside `@spaces.GPU generate_image`.
+    Heavy torch/diffusers imports stay inside the load/gen functions so
+    `build_prompts` (pure) imports cleanly on a CUDA-less box (the pipe itself
+    requires CUDA and does not run on MPS).
+  * `generate_image` returns a PIL Image (picklable; never a CUDA tensor) so it
+    crosses the worker-process boundary cleanly.
+"""
+from __future__ import annotations
+
+import os
+
+import spaces
+
+from witch_wood.core import constants as C
+from witch_wood.core.schema import Property
+
+CONTROLNET_ID = "xinsir/controlnet-scribble-sdxl-1.0"
+SDXL_BASE_ID = "sd-community/sdxl-flash"
+VAE_ID = "madebyollin/sdxl-vae-fp16-fix"
+
+# Prompt scaffolding. Final form:
+#   cinematic photo of <object>: <passed_1>; <passed_2>. <STYLE_SUFFIX>
+# The style/negative strings and the numeric defaults are the single source of
+# truth in witch_wood/core/constants.py (the server exposes them to the tuning
+# panel, which can override any of them per-delivery). Re-exported here so the
+# existing importers (tests, server _gen_options) keep their names.
+STYLE_SUFFIX = C.STYLE_SUFFIX
+BASE_NEGATIVE = C.BASE_NEGATIVE
+DEFAULT_STEPS = C.GEN_STEPS
+DEFAULT_GUIDANCE = C.GEN_GUIDANCE
+DEFAULT_CNET_SCALE = C.GEN_CNET_SCALE
+DEFAULT_SEED = C.GEN_SEED
+
+# Control image fed to the ControlNet. Our canvas is black ink on white; the
+# xinsir scribble model is trained on thin white lines on black, so we invert.
+# The control size also sets the OUTPUT size (SDXL ControlNet renders at the
+# control resolution). Kept below 448x448 so the generated image is a single
+# MiniCPM-V vision tile and the property re-check on the render runs fast.
+# (SDXL-Flash fine-detail at this size is modest; raise if features render poorly.)
+_CONTROL_SIZE = 384
+
+
+def build_prompts(
+    object_name: str,
+    properties: tuple[Property, ...],
+    passes: tuple[bool, ...],
+    style_suffix: str | None = None,
+    base_negative: str | None = None,
+) -> tuple[str, str]:
+    """Construct (prompt, negative_prompt) from the property check result.
+
+    Passed property predicates steer the positive prompt; failed ones are
+    appended to the negative prompt. A request with no passed properties yields
+    a clean `cinematic photo of <object>. <style>` with no dangling `:`/`;`.
+
+    `style_suffix` / `base_negative` override the constants (the tuning panel
+    passes live-edited strings); `None` falls back to C.STYLE_SUFFIX/BASE_NEGATIVE.
+    """
+    style = C.STYLE_SUFFIX if style_suffix is None else style_suffix
+    base_neg = C.BASE_NEGATIVE if base_negative is None else base_negative
+    passed = [p.predicate for p, ok in zip(properties, passes) if ok]
+    failed = [p.predicate for p, ok in zip(properties, passes) if not ok]
+    head = f"cinematic photo of {object_name}"
+    body = (": " + "; ".join(passed)) if passed else ""
+    prompt = f"{head}{body}{style}"
+    negative_properties = ((("; ".join(failed)) + ". ") if failed else "")
+    negative = negative_properties + base_neg
+    return prompt, negative
+
+
+# --- Model loading (module scope, ZeroGPU-registered) -----------------------
+
+_PIPE = None
+
+
+def _ensure_loaded():
+    """Load SDXL-Flash + scribble ControlNet once into a module global.
+
+    On ZeroGPU `import spaces` monkey-patches torch so `.to("cuda")` at module
+    scope registers the weights for device migration; the real GPU is only
+    attached inside the `@spaces.GPU` call that runs generation.
+    """
+    global _PIPE
+    if _PIPE is None:
+        import torch
+        from diffusers import (
+            AutoencoderKL,
+            ControlNetModel,
+            EulerAncestralDiscreteScheduler,
+            StableDiffusionXLControlNetPipeline,
+        )
+
+        controlnet = ControlNetModel.from_pretrained(
+            CONTROLNET_ID, torch_dtype=torch.float16
+        )
+        vae = AutoencoderKL.from_pretrained(VAE_ID, torch_dtype=torch.float16)
+        pipe = StableDiffusionXLControlNetPipeline.from_pretrained(
+            SDXL_BASE_ID, controlnet=controlnet, vae=vae, torch_dtype=torch.float16
+        ).to("cuda")
+        pipe.scheduler = EulerAncestralDiscreteScheduler.from_config(
+            pipe.scheduler.config
+        )
+        _PIPE = pipe
+    return _PIPE
+
+
+def _control_image(image):
+    """Resize the doodle to the control size and invert to white-on-black."""
+    from PIL import ImageOps
+
+    ctrl = image.convert("RGB").resize((_CONTROL_SIZE, _CONTROL_SIZE))
+    return ImageOps.invert(ctrl)
+
+
+def _gen_duration(image, prompt, negative, steps, guidance, cnet_scale, seed) -> int:
+    """Estimate GPU seconds for the quota pre-check. SDXL-Flash is few-step;
+    keep this small (ZeroGPU reserves the full declared duration up front and
+    ranks shorter durations higher) with headroom for cold weight streaming."""
+    return int(steps) + 15
+
+
+def _generate(pipe, image, prompt, negative, steps, guidance, cnet_scale, seed):
+    """Run the diffusion on an already-loaded pipe. Plain helper (no GPU
+    decorator) so it can run inside another module's `@spaces.GPU` entry (the
+    fused delivery pipeline) without nesting GPU acquisitions."""
+    import random as _random
+    import torch
+
+    resolved_seed = _random.randint(0, 2**32 - 1) if int(seed) == -1 else int(seed)
+    control = _control_image(image)
+    result = pipe(
+        prompt=prompt,
+        negative_prompt=negative,
+        image=control,
+        num_inference_steps=int(steps),
+        guidance_scale=float(guidance),
+        controlnet_conditioning_scale=float(cnet_scale),
+        generator=torch.Generator(device="cuda").manual_seed(resolved_seed),
+    )
+    return result.images[0]
+
+
+@spaces.GPU(duration=_gen_duration)
+def generate_image(image, prompt, negative, steps, guidance, cnet_scale, seed):
+    """ZeroGPU entry point: turn a doodle into a polished image.
+
+    The pipe lives in a module global (never pickled); only the PIL doodle and
+    the prompt strings cross into the worker, and a PIL Image crosses back out.
+    """
+    return _generate(_ensure_loaded(), image, prompt, negative,
+                     steps, guidance, cnet_scale, seed)
+
+
+# Trigger the (slow) load eagerly at import so the cold-start cost is paid once
+# at Space startup rather than on the first player's delivery. Gated on the
+# ZeroGPU env so a local CUDA-less import (mac dev / pure prompt tests) does NOT
+# download multi-GB weights or touch CUDA — generate_image lazily loads on its
+# first call there (and the pipe only actually runs on the GPU Space anyway).
+if os.environ.get("SPACES_ZERO_GPU"):
+    _ensure_loaded()

witch_wood/ui/app.py

@@ -0,0 +1,221 @@
+"""Inkwitch — Gradio game UI."""
+from __future__ import annotations
+
+import base64
+import io
+import os
+
+import gradio as gr
+from PIL import Image
+
+from witch_wood.core.state import new_game
+from witch_wood.engine import economy
+from witch_wood.engine.game import deliver, reset_drawing
+from witch_wood.ui.canvas import CANVAS_HTML, CANVAS_JS
+from witch_wood.ui.format import request_card_md, result_md, status_md
+from witch_wood.vision import MockBackend
+
+MOCK = os.environ.get("WITCH_WOOD_MOCK") == "1"
+
+_BACKEND = None
+
+
+def _make_backend():
+    if MOCK:
+        return MockBackend(seed=0)
+    from witch_wood.vision.minicpm import MiniCPMBackend
+    # KV-cache reuse saves ~25% per appraise in separate mode (measured) by not
+    # re-encoding the image on each property call. See scripts/kv_cache_spike.py.
+    return MiniCPMBackend(use_kv_cache=True)
+
+
+def _get_backend():
+    global _BACKEND
+    if _BACKEND is None:
+        _BACKEND = _make_backend()
+    return _BACKEND
+
+
+def _decode_png(data_url: str) -> Image.Image:
+    _, _, b64 = data_url.partition(",")
+    rgba = Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGBA")
+    flat = Image.new("RGB", rgba.size, "white")
+    flat.paste(rgba, mask=rgba.split()[3])
+    return flat
+
+
+def _visitor_choices(g):
+    return [(f"{r.visitor}: {r.object} ({r.base_payment}g)", r.id)
+            for r in g.today if r.id not in g.completed]
+
+
+def start_game():
+    _get_backend()  # load model now; no-op on subsequent calls
+    g = new_game(seed=int.from_bytes(os.urandom(2), "big"))
+    first = g.today[0]
+    choices = _visitor_choices(g)
+    return (
+        g, g.mana, g.mana_max, status_md(g),
+        gr.update(choices=choices, value=first.id),
+        request_card_md(first), "Draw the object, then Deliver.",
+    )
+
+
+def select_visitor(g, request_id):
+    if g is None or request_id is None:
+        return "", gr.update()
+    req = next((r for r in g.today if r.id == request_id), None)
+    if req is None:
+        return "", gr.update()
+    return request_card_md(req), gr.update()
+
+
+def do_deliver(png_data_url, spent_str, g, request_id):
+    if not png_data_url or g is None:
+        return g, g.mana if g else 0, g.mana_max if g else 0, status_md(g) if g else "", "Draw something first.", gr.update()
+    image = _decode_png(png_data_url)
+    spent = int(spent_str or "0")
+    req = next((r for r in g.today if r.id == request_id), None)
+    if req is None:
+        return g, g.mana, g.mana_max, status_md(g), "No request selected.", gr.update()
+    try:
+        result, _ = deliver(g, request_id, image=image, spent_length=spent, backend=_get_backend())
+    except ValueError as e:
+        return g, g.mana, g.mana_max, status_md(g), f"⚠️ {e}", gr.update()
+    remaining = _visitor_choices(g)
+    return (
+        g, g.mana, g.mana_max, status_md(g), result_md(req, result),
+        gr.update(choices=remaining, value=(remaining[0][1] if remaining else None)),
+    )
+
+
+def do_reset(spent_str, g):
+    if g is None:
+        return g, 0, 0, "", "Start a game first."
+    spent = int(spent_str or "0")
+    try:
+        reset_drawing(g, spent)
+    except ValueError as e:
+        return g, g.mana, g.mana_max, status_md(g), f"⚠️ {e}"
+    return g, g.mana, g.mana_max, status_md(g), "🧽 Canvas reset — most of that ink refunded."
+
+
+def do_end_day(g):
+    if g is None:
+        return g, 0, 0, "", "Start a game first.", gr.update()
+    economy.end_day(g)
+    if g.status == "won":
+        return (g, g.mana, g.mana_max, status_md(g), "🎉 **Debt paid — you win! The run is over.**",
+                gr.update(choices=[]))
+    if g.status == "lost":
+        reason = ("⏰ **Deadline reached short of the debt — game over.**"
+                  if g.day >= g.deadline_day else "💀 **Bankrupt — game over.**")
+        return g, g.mana, g.mana_max, status_md(g), reason, gr.update(choices=[])
+    nxt = _visitor_choices(g)
+    return (g, g.mana, g.mana_max, status_md(g), "A new day dawns.",
+            gr.update(choices=nxt, value=(nxt[0][1] if nxt else None)))
+
+
+def buy(g, kind):
+    if g is None:
+        return g, 0, 0, "", "Start a game first."
+    try:
+        {"potion": economy.buy_potion, "mana": economy.buy_mana_upgrade}[kind](g)
+        msg = f"Bought {kind}."
+    except ValueError as e:
+        msg = str(e)
+    return g, g.mana, g.mana_max, status_md(g), msg
+
+
+def build_demo() -> gr.Blocks:
+    # Reset lazy backend when building demo so MOCK env var is re-evaluated
+    global _BACKEND, MOCK
+    MOCK = os.environ.get("WITCH_WOOD_MOCK") == "1"
+    _BACKEND = None
+
+    with gr.Blocks(title="Inkwitch") as demo:
+        state = gr.State(None)
+        # gr.State never sends its value to the JS frontend (always null on the
+        # client). Use a hidden gr.Number so the updated mana value is actually
+        # serialised and delivered to the .then() JS callbacks.
+        mana_state = gr.Number(value=0, visible=False)
+        mana_max_state = gr.Number(value=0, visible=False)
+        gr.Markdown("# 🧙‍♀️ Inkwitch\nDraw to pay your debt before the deadline.")
+        status = gr.Markdown("")
+        with gr.Row():
+            with gr.Column():
+                visitor = gr.Radio(label="Visitors", choices=[], interactive=True)
+                card = gr.Markdown("")
+                gr.HTML(CANVAS_HTML)
+                png_field = gr.Textbox(visible=False, elem_id="iw-png")
+                spent_field = gr.Textbox(visible=False, elem_id="iw-spent")
+                with gr.Row():
+                    deliver_btn = gr.Button("Deliver ✒️", variant="primary")
+                    reset_btn = gr.Button("Reset canvas 🧽")
+            with gr.Column():
+                outcome = gr.Markdown("")
+                with gr.Row():
+                    potion_btn = gr.Button("Potion 🧪")
+                    mana_btn = gr.Button("+Max mana 🔮")
+                end_btn = gr.Button("End day 🌙", variant="secondary")
+                start_btn = gr.Button("New game ▶️")
+
+        demo.load(None, None, None, js=CANVAS_JS)
+
+        # Combined JS: re-runs the canvas init (idempotent — _ready guard prevents
+        # double-setup) then sets the budget. Needed because demo.load may fire
+        # before gr.HTML renders the canvas into the DOM, leaving window.inkwitch
+        # undefined. By "New game" click time, the DOM is settled.
+        _init_and_arm = f"(m, mx) => {{ ({CANVAS_JS})(); window.inkwitch.setMana(Number(m), Number(mx)); }}"
+
+        start_btn.click(
+            start_game, None,
+            [state, mana_state, mana_max_state, status, visitor, card, outcome],
+        ).then(None, [mana_state, mana_max_state], None, js=_init_and_arm)
+
+        visitor.change(select_visitor, [state, visitor], [card, outcome])
+
+        # Deliver: Gradio 6 passes ALL inputs (including gr.State) as JS args,
+        # so there are 4 args: (png_val, spent_val, state_val, visitor_val).
+        # We capture all 4 explicitly, replace png/spent from the canvas, pass
+        # state (st) back unchanged (Gradio uses its server-side copy anyway),
+        # and forward the visitor value in position [3].
+        deliver_btn.click(
+            do_deliver, [png_field, spent_field, state, visitor],
+            [state, mana_state, mana_max_state, status, outcome, visitor],
+            js="(p, s, st, v) => { const [png, spent] = window.inkwitch.getResult(); return [png, spent, st, v]; }",
+        ).then(None, [mana_state, mana_max_state], None,
+               js="(m, mx) => { window.inkwitch && window.inkwitch.setMana(Number(m), Number(mx)); }")
+
+        # Reset: inputs are [spent_field, state]. Gradio passes both as JS args.
+        # Capture state (st) at position [1] and pass it back unchanged.
+        reset_btn.click(
+            do_reset, [spent_field, state],
+            [state, mana_state, mana_max_state, status, outcome],
+            js="(s, st) => [window.inkwitch.getResult()[1], st]",
+        ).then(None, [mana_state, mana_max_state], None,
+               js="(m, mx) => { window.inkwitch && window.inkwitch.setMana(Number(m), Number(mx)); }")
+
+        end_btn.click(
+            do_end_day, [state],
+            [state, mana_state, mana_max_state, status, outcome, visitor],
+        ).then(None, [mana_state, mana_max_state], None,
+               js="(m, mx) => { window.inkwitch && window.inkwitch.setMana(Number(m), Number(mx)); }")
+
+        potion_btn.click(
+            lambda g: buy(g, "potion"), [state],
+            [state, mana_state, mana_max_state, status, outcome],
+        ).then(None, [mana_state, mana_max_state], None,
+               js="(m, mx) => { window.inkwitch && window.inkwitch.updateMana(Number(m), Number(mx)); }")
+
+        mana_btn.click(
+            lambda g: buy(g, "mana"), [state],
+            [state, mana_state, mana_max_state, status, outcome],
+        ).then(None, [mana_state, mana_max_state], None,
+               js="(m, mx) => { window.inkwitch && window.inkwitch.updateMana(Number(m), Number(mx)); }")
+
+    return demo
+
+
+if __name__ == "__main__":
+    build_demo().launch()

witch_wood/ui/canvas.py

@@ -0,0 +1,81 @@
+"""Client-side mana-metered drawing canvas (Approach A).
+
+The browser owns drawing, stroke-length metering, the mana bar, and the hard
+stop. On Deliver, JS writes {png, spent} into two hidden Gradio textboxes so a
+Python handler can read them. Python never sees intermediate strokes.
+"""
+from __future__ import annotations
+
+CANVAS_WIDTH = 384
+CANVAS_HEIGHT = 384
+
+CANVAS_HTML = f"""
+<div id="iw-wrap" style="display:flex;flex-direction:column;gap:8px;max-width:{CANVAS_WIDTH}px">
+  <div style="background:#eee;border-radius:6px;height:14px;overflow:hidden">
+    <div id="iw-mana" style="background:#6c63ff;height:100%;width:100%"></div>
+  </div>
+  <div id="iw-mana-label" style="font:12px monospace;color:#555">mana: -- / --</div>
+  <canvas id="iw-canvas" width="{CANVAS_WIDTH}" height="{CANVAS_HEIGHT}"
+          style="border:1px solid #999;border-radius:6px;background:#fff;touch-action:none;cursor:crosshair">
+  </canvas>
+</div>
+"""
+
+# Defines window.inkwitch with setBudget/reset/getResult and wires pointer events.
+CANVAS_JS = """
+() => {
+  if (window.inkwitch && window.inkwitch._ready) return;
+  const canvas = document.getElementById('iw-canvas');
+  const bar = document.getElementById('iw-mana');
+  const label = document.getElementById('iw-mana-label');
+  if (!canvas) return;
+  const ctx = canvas.getContext('2d');
+  ctx.lineWidth = 3; ctx.lineCap = 'round'; ctx.lineJoin = 'round'; ctx.strokeStyle = '#111';
+
+  let budget = 0, previous_spent = 0, current_spent = 0, drawing = false, last = null;
+
+  function refresh() {
+    const total_spent = previous_spent + current_spent;
+    const remaining = Math.max(0, budget - total_spent);
+    const pct = budget > 0 ? (remaining / budget) * 100 : 0;
+    bar.style.width = Math.min(100, Math.max(0, pct)) + '%';
+    bar.style.background = pct < 20 ? '#e0526a' : '#6c63ff';
+    label.textContent = 'mana: ' + Math.round(remaining) + ' / ' + Math.round(budget);
+  }
+  function pos(e) {
+    const r = canvas.getBoundingClientRect();
+    return {
+      x: (e.clientX - r.left) * (canvas.width / r.width),
+      y: (e.clientY - r.top) * (canvas.height / r.height)
+    };
+  }
+  canvas.addEventListener('pointerdown', (e) => {
+    if (previous_spent + current_spent >= budget) return;
+    drawing = true; last = pos(e); canvas.setPointerCapture(e.pointerId);
+  });
+  canvas.addEventListener('pointermove', (e) => {
+    if (!drawing) return;
+    const p = pos(e);
+    const seg = Math.hypot(p.x - last.x, p.y - last.y);
+    if (previous_spent + current_spent + seg > budget) {            // hard stop: clip to remaining and end
+      drawing = false; refresh(); return;
+    }
+    ctx.beginPath(); ctx.moveTo(last.x, last.y); ctx.lineTo(p.x, p.y); ctx.stroke();
+    current_spent += seg; last = p; refresh();
+  });
+  function endStroke() { drawing = false; }
+  canvas.addEventListener('pointerup', endStroke);
+  canvas.addEventListener('pointercancel', endStroke);
+  canvas.addEventListener('pointerleave', endStroke);
+
+  window.inkwitch = {
+    _ready: true,
+    setBudget(n) { budget = n; previous_spent = 0; current_spent = 0; ctx.clearRect(0,0,canvas.width,canvas.height); refresh(); },
+    setMana(remaining, max) { budget = Math.max(max, remaining); previous_spent = Math.max(0, budget - remaining); current_spent = 0; ctx.clearRect(0,0,canvas.width,canvas.height); refresh(); },
+    updateMana(remaining, max) { budget = Math.max(max, remaining); previous_spent = Math.max(0, budget - remaining); refresh(); },
+    reset() { current_spent = 0; ctx.clearRect(0,0,canvas.width,canvas.height); refresh(); },
+    getResult() { return [canvas.toDataURL('image/png'), String(Math.round(current_spent))]; }
+  };
+  refresh();
+}
+"""

witch_wood/ui/format.py

@@ -0,0 +1,42 @@
+# witch_wood/ui/format.py
+"""Pure Markdown formatters for the Gradio UI."""
+from __future__ import annotations
+
+from witch_wood.core.schema import DeliverResult, Request
+from witch_wood.core.state import GameState
+from witch_wood.engine.economy import current_potion_price
+
+
+def request_card_md(req: Request) -> str:
+    props = "\n".join(f"- ☆ {p.predicate}" for p in req.properties)
+    body = f"\n\n{props}" if props else ""
+    return (
+        f"**{req.visitor}** wants a **{req.object}** — *{req.flavor}*{body}\n\n"
+        f"Offers **{req.base_payment}** gold"
+    )
+
+
+def result_md(req: Request, res: DeliverResult) -> str:
+    seen = f"\n\n*The witch sees: {res.description}*" if res.description else ""
+    rec = "✅ Recognized" if res.recognized else "❌ Not recognized"
+    if not res.recognized:
+        return (
+            f"{rec} as a **{req.object}** — "
+            f"base payment (50%) **{res.payment} gold**.{seen}"
+        )
+    marks = "\n".join(
+        f"- {'★' if ok else '☆'} {p.label}"
+        for p, ok in zip(req.properties, res.passes)
+    )
+    body = f"\n\n{marks}" if marks else ""
+    return f"{rec} as a **{req.object}**{body}\n\n**{res.stars}/{req.tier} stars → {res.payment} gold**{seen}"
+
+
+def status_md(g: GameState) -> str:
+    return (
+        f"**Day {g.day}/{g.deadline_day}**  ·  "
+        f"💰 {g.gold}  ·  🔮 mana {g.mana}/{g.mana_max}  ·  "
+        f"🪑 slots {g.slots}  ·  ⭐ {g.total_stars}  ·  "
+        f"🧪 {current_potion_price(g)}  ·  "
+        f"debt {g.debt}"
+    )

witch_wood/ui/server.py

@@ -0,0 +1,503 @@
+# witch_wood/ui/server.py
+"""Gradio Server backend for the hand-drawn Inkwitch UI."""
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+import threading
+from collections import OrderedDict
+from PIL import Image
+
+import gradio as gr
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from witch_wood.core import constants as C
+from witch_wood.core.state import new_game, GameState
+from witch_wood.engine import economy
+from witch_wood.engine.game import deliver, reset_drawing
+from witch_wood.ui.format import request_card_md, result_md, status_md
+from witch_wood.vision.mock import MockBackend
+
+MOCK = os.environ.get("WITCH_WOOD_MOCK") == "1"
+
+
+def _make_backend():
+    if MOCK:
+        return MockBackend(seed=0)
+    # Importing minicpm loads MiniCPM-V at module scope (registered for ZeroGPU
+    # device migration). Done eagerly at startup so the cold-start cost is paid
+    # once here rather than on the first player's delivery.
+    from witch_wood.vision.minicpm import MiniCPMBackend
+    return MiniCPMBackend(use_kv_cache=True)
+
+
+# Eager singleton: the model is loaded when this module is imported (Space
+# startup), before any GPU request arrives. The model is read-only during
+# inference, so sharing this one instance across concurrent requests is safe.
+_BACKEND = _make_backend()
+
+
+def _get_backend():
+    return _BACKEND
+
+
+# Image-gen second stage. Importing `scribble` eagerly loads the SDXL-Flash +
+# ControlNet pipe at module scope (Space startup) — same eager-load rationale as
+# the vision backend. Skipped under MOCK so local CUDA-less dev never pulls in
+# the GPU pipe (which requires CUDA and does not run on MPS).
+if not MOCK:
+    # Importing `pipeline` pulls in both scribble (SDXL pipe) and minicpm
+    # (MiniCPM-V) and eager-loads them at module scope — the fused delivery runs
+    # all three model calls (appraise + gen + render re-check) in one GPU entry.
+    from witch_wood.gen import pipeline
+else:
+    pipeline = None
+
+
+# --- Per-session game state -------------------------------------------------
+#
+# @app.api endpoints serialize calls through Gradio's queue (concurrency_limit),
+# but they do NOT isolate state per user — so each visitor needs their own
+# GameState. We key it on `gr.Request.session_hash`, which is unique per
+# @gradio/client connection (one per browser tab) and stable across that
+# connection's calls. An LRU cap bounds memory from abandoned sessions.
+MAX_SESSIONS = 500
+_SESSIONS_LOCK = threading.Lock()
+
+# session_hash -> GameState
+GAMES: "OrderedDict[str, GameState]" = OrderedDict()
+# session_hash -> {visitor_id -> result breakdown}  (today's completed deliveries)
+RESULTS: "OrderedDict[str, dict[str, dict]]" = OrderedDict()
+
+
+def _session_id(request: gr.Request | None) -> str:
+    """Stable per-connection key. Direct API callers without a Gradio session
+    (e.g. raw curl) all share one fallback bucket."""
+    sid = getattr(request, "session_hash", None) if request is not None else None
+    return sid or "_anonymous"
+
+
+def _start_session(request: gr.Request | None, test_mode: bool | None = None) -> GameState:
+    """Create a fresh game (and empty results) for this session, evicting the
+    least-recently-used sessions past the cap. `test_mode=True` forces the harness
+    on for this session (hidden 5-reset gesture); None falls back to the env const."""
+    sid = _session_id(request)
+    game = new_game(seed=int.from_bytes(os.urandom(2), "big"), test_mode=test_mode)
+    with _SESSIONS_LOCK:
+        GAMES[sid] = game
+        GAMES.move_to_end(sid)
+        RESULTS[sid] = {}
+        RESULTS.move_to_end(sid)
+        while len(GAMES) > MAX_SESSIONS:
+            old_sid, _ = GAMES.popitem(last=False)
+            RESULTS.pop(old_sid, None)
+    return game
+
+
+def _session(request: gr.Request | None) -> tuple[GameState | None, dict[str, dict]]:
+    """Return (game, results) for this session; game is None if not started."""
+    sid = _session_id(request)
+    with _SESSIONS_LOCK:
+        game = GAMES.get(sid)
+        if game is not None:
+            GAMES.move_to_end(sid)
+        results = RESULTS.setdefault(sid, {})
+    return game, results
+
+
+app = gr.Server()
+
+# Mount static folder for assets, CSS, JS
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+os.makedirs(STATIC_DIR, exist_ok=True)
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+def _decode_png(data_url: str) -> Image.Image:
+    _, _, b64 = data_url.partition(",")
+    rgba = Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGBA")
+    flat = Image.new("RGB", rgba.size, "white")
+    flat.paste(rgba, mask=rgba.split()[3])
+    return flat
+
+
+def _encode_png(image: Image.Image) -> str:
+    """Encode a PIL image as a base64 PNG data URL for the frontend."""
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
+# --- image-gen tuning panel -------------------------------------------------
+# The gen flag/params/prompt-suffixes live in constants.py (single source). The
+# panel's default values are rendered into the HTML from those constants by
+# _render_index; here we parse the panel's `gen_opts` JSON back, overriding any
+# field (blank text falls back to the constant).
+def _gen_options(gen_opts: str) -> dict:
+    try:
+        opts = json.loads(gen_opts) if gen_opts else {}
+    except (ValueError, TypeError):
+        opts = {}
+    # Blank textareas -> fall back to the constants (treat ""/whitespace as unset).
+    style = str(opts.get("style_suffix") or "").strip() or C.STYLE_SUFFIX
+    negative = str(opts.get("base_negative") or "").strip() or C.BASE_NEGATIVE
+    return {
+        "enabled": bool(opts.get("enabled", C.GEN_ENABLED)),
+        "steps": int(opts.get("steps", C.GEN_STEPS)),
+        "guidance": float(opts.get("guidance", C.GEN_GUIDANCE)),
+        "controlnet_scale": float(opts.get("controlnet_scale", C.GEN_CNET_SCALE)),
+        "seed": int(opts.get("seed", C.GEN_SEED)),
+        "style_suffix": style,
+        "base_negative": negative,
+    }
+
+
+def _get_visitor_list(g: GameState, results: dict[str, dict]) -> list[dict]:
+    """Helper to serialize today's visitor queue (including completed ones)."""
+    visitors_data = []
+    for r in g.today:
+        is_completed = r.id in g.completed
+        result_breakdown = results.get(r.id)
+
+        visitors_data.append({
+            "id": r.id,
+            "visitor": r.visitor,
+            "object": r.object,
+            "base_payment": r.base_payment,
+            "actual_payment": result_breakdown["total_payment"] if is_completed and result_breakdown else None,
+            "flavor": r.flavor,
+            "tier": r.tier,
+            "properties": [{"label": p.label, "predicate": p.predicate} for p in r.properties],
+            "completed": is_completed,
+            "breakdown": result_breakdown,
+            "doodle": result_breakdown.get("doodle") if is_completed and result_breakdown else None,
+            "generated": result_breakdown.get("generated") if is_completed and result_breakdown else None
+        })
+    return visitors_data
+
+
+def _get_game_payload(g: GameState) -> dict:
+    """Helper to serialize the general game state."""
+    return {
+        "day": g.day,
+        "deadline_day": g.deadline_day,
+        "gold": g.gold,
+        "debt": g.debt,
+        "rent": g.rent,
+        "mana": g.mana,
+        "mana_max": g.mana_max,
+        "slots": g.slots,
+        "total_stars": g.total_stars,
+        "potion_price": economy.current_potion_price(g),
+        "max_mana_price": C.MANA_UPGRADE_COST,
+        "status": g.status,
+        "potions_bought_today": g.potions_bought_today,
+        "slot_unlock_stars": {str(k): v for k, v in C.SLOT_UNLOCK_STARS.items()},
+        "logs": g.logs,
+    }
+
+
+def _render_index(html: str) -> str:
+    """Fill the image-gen panel's `{{WW_*}}` tokens from the Python constants so
+    the panel defaults are always in sync with constants.py (single source of
+    truth) — never hardcoded in the static HTML."""
+    import html as _html
+
+    repl = {
+        "{{WW_GEN_ENABLED_CHECKED}}": "checked" if C.GEN_ENABLED else "",
+        "{{WW_GEN_STEPS}}": str(C.GEN_STEPS),
+        "{{WW_GEN_GUIDANCE}}": str(C.GEN_GUIDANCE),
+        "{{WW_GEN_CNET_SCALE}}": str(C.GEN_CNET_SCALE),
+        "{{WW_GEN_SEED}}": str(C.GEN_SEED),
+        # textarea body: escape so any markup-special chars stay literal text
+        "{{WW_STYLE_SUFFIX}}": _html.escape(C.STYLE_SUFFIX),
+        "{{WW_BASE_NEGATIVE}}": _html.escape(C.BASE_NEGATIVE),
+        # Game economy constants
+        "{{WW_RENT}}": str(C.RENT),
+        "{{WW_DEBT}}": str(C.DEBT),
+        "{{WW_DEADLINE_DAY}}": str(C.DEADLINE_DAY),
+        "{{WW_POTION_MANA}}": str(C.POTION_MANA),
+        "{{WW_MANA_UPGRADE_AMOUNT}}": str(C.MANA_UPGRADE_AMOUNT),
+        "{{WW_CANVAS_RESET_REFUND_PCT}}": str(int(C.CANVAS_RESET_REFUND * 100)),
+    }
+    for token, value in repl.items():
+        html = html.replace(token, value)
+    return html
+
+
+@app.get("/", response_class=HTMLResponse)
+def get_index():
+    index_path = os.path.join(STATIC_DIR, "index.html")
+    if not os.path.exists(index_path):
+        return HTMLResponse("<h1>Static files not created yet!</h1><p>Please wait for the static assets to build.</p>")
+    with open(index_path, "r", encoding="utf-8") as f:
+        return _render_index(f.read())
+
+
+@app.api(name="start_game")
+def api_start_game(request: gr.Request) -> dict:
+    """Initializes a new game for this visitor's session.
+
+    Always starts in NORMAL mode — test mode is opt-in via the hidden 5-reset
+    gesture (`enable_testmode`), never the default, even if the Space still has
+    the legacy `WITCH_WOOD_TESTMODE` variable set."""
+    g = _start_session(request, test_mode=False)
+
+    visitors = _get_visitor_list(g, {})
+    payload = _get_game_payload(g)
+
+    return {
+        "success": True,
+        "game": payload,
+        "visitors": visitors,
+        "selected_visitor_id": visitors[0]["id"] if visitors else None,
+    }
+
+
+@app.api(name="enable_testmode")
+def api_enable_testmode(request: gr.Request) -> dict:
+    """Hidden harness gesture (frontend: 5 consecutive Reset clicks): start a fresh
+    game with test mode forced on for this session (unlimited gold/mana, full
+    visitor pool, repeat delivery). Refresh the page to return to a normal run."""
+    g = _start_session(request, test_mode=True)
+
+    visitors = _get_visitor_list(g, {})
+    payload = _get_game_payload(g)
+
+    return {
+        "success": True,
+        "game": payload,
+        "visitors": visitors,
+        "selected_visitor_id": visitors[0]["id"] if visitors else None,
+        "message": "🧪 Test mode enabled — unlimited gold & mana, full visitor pool.",
+    }
+
+
+@app.api(name="select_visitor")
+def api_select_visitor(visitor_id: str, request: gr.Request) -> dict:
+    """Returns the details of a specific visitor request."""
+    g, results = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    req = next((r for r in g.today if r.id == visitor_id), None)
+    if req is None:
+        return {"success": False, "error": "Visitor not found"}
+
+    is_completed = req.id in g.completed
+    result_breakdown = results.get(req.id)
+
+    return {
+        "success": True,
+        "visitor": {
+            "id": req.id,
+            "visitor": req.visitor,
+            "object": req.object,
+            "base_payment": req.base_payment,
+            "actual_payment": result_breakdown["total_payment"] if is_completed and result_breakdown else None,
+            "flavor": req.flavor,
+            "tier": req.tier,
+            "properties": [{"label": p.label, "predicate": p.predicate} for p in req.properties],
+            "completed": is_completed,
+            "breakdown": result_breakdown,
+            "doodle": result_breakdown.get("doodle") if is_completed and result_breakdown else None,
+            "generated": result_breakdown.get("generated") if is_completed and result_breakdown else None
+        }
+    }
+
+
+@app.api(name="deliver")
+def api_deliver(png_data_url: str, spent_mana: int, visitor_id: str, gen_opts: str = "", request: gr.Request = None) -> dict:
+    """Processes canvas drawing delivery and grades it.
+
+    `gen_opts` is a TEMPORARY JSON string from the image-gen tuning panel
+    ({enabled, steps, guidance, controlnet_scale, seed}); remove it along with
+    the panel once the params are tuned.
+    """
+    g, results = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    if not png_data_url:
+        return {"success": False, "error": "Draw something first!"}
+
+    req = next((r for r in g.today if r.id == visitor_id), None)
+    if req is None:
+        return {"success": False, "error": "Visitor not found"}
+
+    try:
+        # Decode base64 canvas image
+        image = _decode_png(png_data_url)
+
+        # Build the fused GPU pipeline. It runs INSIDE deliver() and does the
+        # whole delivery — doodle appraisal, image-gen (object + doodle
+        # passed/failed properties injected into the prompt), and the render
+        # re-check — in ONE @spaces.GPU acquisition, returning (verdict, render).
+        # `gen_opts["enabled"]` toggles the image-gen stage; when off (or under
+        # MOCK, where pipeline is None) scoring falls back to the doodle.
+        gpu_pipeline = None
+        if pipeline is not None:
+            opts = _gen_options(gen_opts)
+
+            def gpu_pipeline(img, request):
+                return pipeline.run_delivery_gpu(img, request, opts)
+
+        # Execute deliver logic
+        res, gen_img = deliver(
+            g,
+            visitor_id,
+            image=image,
+            spent_length=int(spent_mana),
+            backend=_get_backend(),
+            gpu_pipeline=gpu_pipeline,
+        )
+
+        # Calculate structured payment breakdown details
+        is_recognized = res.recognized
+        base_payment = req.base_payment
+        total_payment = res.payment
+
+        if is_recognized:
+            base_payment_earned = base_payment # 100% of base
+            bonus_percent = C.STAR_BONUS_PER_STAR * res.stars
+            bonus_earned = round(base_payment * bonus_percent)
+            penalty_subtracted = 0
+        else:
+            base_payment_earned = round(base_payment * C.RECOGNITION_FAIL_PAYOUT) # 50% flat consolation
+            bonus_earned = 0
+            penalty_subtracted = base_payment - base_payment_earned
+
+        breakdown = {
+            "recognized": is_recognized,
+            "base_payment": base_payment,
+            "recognition_passed": is_recognized,
+            "stars_earned": res.stars,
+            "star_multiplier": C.STAR_BONUS_PER_STAR,
+            "base_payment_earned": base_payment_earned,
+            "bonus_earned": bonus_earned,
+            "penalty_subtracted": penalty_subtracted,
+            "total_payment": total_payment,
+            "description": res.description,
+            "passes": list(res.passes),
+            "doodle": png_data_url,
+            "generated": _encode_png(gen_img) if gen_img is not None else None,
+        }
+
+        # Store in this session's completed results map
+        results[visitor_id] = breakdown
+
+        visitors = _get_visitor_list(g, results)
+        payload = _get_game_payload(g)
+
+        return {
+            "success": True,
+            "game": payload,
+            "visitors": visitors,
+            "selected_visitor_id": visitor_id,  # Keep the delivered guest selected to view outcomes
+            "breakdown": breakdown
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@app.api(name="reset_canvas")
+def api_reset_canvas(spent_mana: int, request: gr.Request) -> dict:
+    """Refunds part of the spent mana and clears canvas budget."""
+    g, _ = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    try:
+        new_mana = reset_drawing(g, int(spent_mana))
+        payload = _get_game_payload(g)
+        return {
+            "success": True,
+            "game": payload,
+            "message": "🧽 Canvas reset — most of that ink refunded!"
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@app.api(name="buy_potion")
+def api_buy_potion(request: gr.Request) -> dict:
+    """Purchases a mana-refill potion from the shop."""
+    g, _ = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    try:
+        economy.buy_potion(g)
+        payload = _get_game_payload(g)
+        return {
+            "success": True,
+            "game": payload,
+            "message": "🧪 Bought mana potion!"
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@app.api(name="buy_max_mana")
+def api_buy_max_mana(request: gr.Request) -> dict:
+    """Upgrades the player's max mana capacity."""
+    g, _ = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    try:
+        economy.buy_mana_upgrade(g)
+        payload = _get_game_payload(g)
+        return {
+            "success": True,
+            "game": payload,
+            "message": "🔮 Max mana capacity upgraded!"
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+@app.api(name="end_day")
+def api_end_day(request: gr.Request) -> dict:
+    """Triggers nightfall, checks win/loss debt conditions, refills mana, advances day."""
+    g, results = _session(request)
+    if g is None:
+        return {"success": False, "error": "Game not started"}
+
+    try:
+        old_day = g.day
+        old_gold = g.gold
+        rent = g.rent
+        debt = g.debt
+
+        economy.end_day(g)
+        results.clear()  # reset completed guest records for the new day
+
+        payload = _get_game_payload(g)
+        visitors = _get_visitor_list(g, results)
+
+        # Determine night message
+        if g.status == "won":
+            msg = "🎉 **Debt paid — you win! The run is over.**"
+        elif g.status == "lost":
+            if old_day >= g.deadline_day:
+                msg = "⏰ **Deadline reached short of the debt — game over.**"
+            else:
+                msg = "💀 **Bankrupt — game over.**"
+        else:
+            msg = f"🌙 Paid rent ({rent}g). A new day dawns!"
+
+        return {
+            "success": True,
+            "game": payload,
+            "visitors": visitors,
+            "selected_visitor_id": visitors[0]["id"] if visitors else None,
+            "message": msg
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

witch_wood/ui/static/app.js

@@ -0,0 +1,895 @@
+// app.js - Inkwitch Redesign Client Controller
+
+// State variables
+let gameState = null;
+let visitors = [];
+let selectedVisitorId = null;
+let spentMana = 0;
+let drawing = false;
+let lastPos = null;
+let isDelivering = false;
+let resetStreak = 0;  // consecutive Reset clicks; 5 in a row flips on test mode
+
+// DOM Elements
+const canvas = document.getElementById('paint-canvas');
+const ctx = canvas.getContext('2d');
+const manaText = document.getElementById('mana-text');
+const manaBarInner = document.getElementById('mana-bar-inner');
+const visitorsList = document.getElementById('visitors-list');
+const visitorRequestCard = document.getElementById('visitor-request-card');
+const outcomeContent = document.getElementById('outcome-content');
+
+// Status board elements
+const statDay = document.getElementById('stat-day');
+const statGold = document.getElementById('stat-gold');
+const statDebt = document.getElementById('stat-debt');
+const statStars = document.getElementById('stat-stars');
+
+// Shop elements
+const costPotion = document.getElementById('cost-potion');
+const costMaxMana = document.getElementById('cost-max-mana');
+
+// Buttons
+const btnReset = document.getElementById('btn-reset');
+const btnDeliver = document.getElementById('btn-deliver');
+const btnBuyPotion = document.getElementById('btn-buy-potion');
+const btnBuyMax = document.getElementById('btn-buy-max');
+const btnEndDay = document.getElementById('btn-end-day');
+const btnNewGame = document.getElementById('btn-new-game');
+const btnInstructions = document.getElementById('btn-instructions');
+const btnCloseInstructions = document.getElementById('btn-close-instructions');
+const instructionsModal = document.getElementById('instructions-modal');
+
+
+// Configure Canvas Stroke
+ctx.lineWidth = 4;
+ctx.lineCap = 'round';
+ctx.lineJoin = 'round';
+ctx.strokeStyle = '#2c2825'; // Matches charcoal ink
+
+// Canvas drawing coordinate helper
+function getPos(e) {
+  const rect = canvas.getBoundingClientRect();
+  // Support both mouse and touch events
+  const clientX = e.clientX || (e.touches && e.touches[0].clientX);
+  const clientY = e.clientY || (e.touches && e.touches[0].clientY);
+
+  // Scale coordinates to match internal canvas drawing space when visually resized
+  return {
+    x: (clientX - rect.left) * (canvas.width / rect.width),
+    y: (clientY - rect.top) * (canvas.height / rect.height)
+  };
+}
+
+// Update the mana visual indicators
+function updateManaBar() {
+  if (!gameState) return;
+  const currentAvailable = Math.max(0, gameState.mana - spentMana);
+  const percent = gameState.mana_max > 0 ? (currentAvailable / gameState.mana_max) * 100 : 0;
+  
+  manaText.textContent = `${Math.round(currentAvailable)} / ${gameState.mana_max}`;
+  manaBarInner.style.width = `${Math.min(100, Math.max(0, percent))}%`;
+  
+  // Set alert color when mana is low (under 20%)
+  if (percent < 20) {
+    manaBarInner.style.backgroundColor = 'var(--color-error)';
+  } else {
+    manaBarInner.style.backgroundColor = 'var(--color-primary)';
+  }
+}
+
+// Canvas Event Listeners
+canvas.addEventListener('pointerdown', (e) => {
+  if (!gameState || gameState.status !== 'playing' || isDelivering) return;
+  if (gameState.mana - spentMana <= 0) return;
+
+  drawing = true;
+  lastPos = getPos(e);
+  canvas.setPointerCapture(e.pointerId);
+});
+
+canvas.addEventListener('pointermove', (e) => {
+  if (!drawing || isDelivering) return;
+  
+  const currentPos = getPos(e);
+  const segmentLength = Math.hypot(currentPos.x - lastPos.x, currentPos.y - lastPos.y);
+  
+  // Hard stop check: limit drawing by remaining mana
+  if (spentMana + segmentLength > gameState.mana) {
+    drawing = false;
+    updateManaBar();
+    return;
+  }
+  
+  ctx.beginPath();
+  ctx.moveTo(lastPos.x, lastPos.y);
+  ctx.lineTo(currentPos.x, currentPos.y);
+  ctx.stroke();
+  
+  spentMana += segmentLength;
+  lastPos = currentPos;
+  updateManaBar();
+});
+
+function endDrawing() {
+  drawing = false;
+}
+
+canvas.addEventListener('pointerup', endDrawing);
+canvas.addEventListener('pointercancel', endDrawing);
+canvas.addEventListener('pointerleave', endDrawing);
+
+// Clear canvas visually
+function clearCanvas() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+}
+
+// Bleeding effect animation loop and helper variables
+let bleedInterval = null;
+let originalCanvas = null;
+let tempCanvas = null;
+
+function startBleedingEffect() {
+  if (!canvas || !ctx) return;
+
+  // Save the original drawing to a background canvas
+  originalCanvas = document.createElement('canvas');
+  originalCanvas.width = canvas.width;
+  originalCanvas.height = canvas.height;
+  const origCtx = originalCanvas.getContext('2d');
+  origCtx.drawImage(canvas, 0, 0);
+
+  // Create a temp canvas for double-buffered diffusion rendering
+  tempCanvas = document.createElement('canvas');
+  tempCanvas.width = canvas.width;
+  tempCanvas.height = canvas.height;
+  const tempCtx = tempCanvas.getContext('2d');
+
+  let frameCount = 0;
+
+  function bleedStep() {
+    if (!isDelivering) {
+      cleanupBleed();
+      return;
+    }
+
+    frameCount++;
+
+    // Heartbeat rhythm (60 frames = ~1s): short strong pulse then slow diffusion
+    const cycleFrames = 60;
+    const phase = frameCount % cycleFrames;
+    let jitterStrength = 0.15;
+    let pulseScale = 1.0001;
+    let blurRadius = 0.0;
+
+    if (phase < 12) { // strong phase (first 0.2s of each cycle)
+      const progress = phase / 12;
+      const pulseFactor = Math.sin(progress * Math.PI);
+
+      jitterStrength = 0.15 + pulseFactor * 5;
+      pulseScale = 1.0001 + pulseFactor * 0.0025;
+      blurRadius = 0.25 + pulseFactor * 0.65;
+    }
+
+    // Copy current canvas contents to temp canvas
+    tempCtx.clearRect(0, 0, tempCanvas.width, tempCanvas.height);
+    tempCtx.drawImage(canvas, 0, 0);
+
+    // Clear main canvas
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+    // Diffusion step: blur + fade + scale outward + jitter
+    ctx.save();
+    if (typeof ctx.filter !== 'undefined') {
+      ctx.filter = `blur(${blurRadius}px)`;
+    }
+    ctx.globalAlpha = 0.975;
+    ctx.translate(canvas.width / 2, canvas.height / 2);
+    ctx.scale(pulseScale, pulseScale);
+    ctx.translate(-canvas.width / 2, -canvas.height / 2);
+    const dx = (Math.random() - 0.5) * jitterStrength;
+    const dy = (Math.random() - 0.5) * jitterStrength;
+    ctx.drawImage(tempCanvas, dx, dy);
+    ctx.restore();
+
+    // Feed a faint copy of the original to keep the core ink lines alive
+    ctx.save();
+    ctx.globalAlpha = 0.035;
+    ctx.drawImage(originalCanvas, 0, 0);
+    ctx.restore();
+
+    bleedInterval = requestAnimationFrame(bleedStep);
+  }
+
+  bleedInterval = requestAnimationFrame(bleedStep);
+}
+
+function stopBleedingEffect(deliverySuccessful) {
+  if (bleedInterval) {
+    cancelAnimationFrame(bleedInterval);
+    bleedInterval = null;
+  }
+  // Restore original drawing if delivery failed or was cancelled
+  if (!deliverySuccessful && originalCanvas) {
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.drawImage(originalCanvas, 0, 0);
+  }
+  originalCanvas = null;
+  tempCanvas = null;
+}
+
+function cleanupBleed() {
+  if (bleedInterval) {
+    cancelAnimationFrame(bleedInterval);
+    bleedInterval = null;
+  }
+  originalCanvas = null;
+  tempCanvas = null;
+}
+
+// Connect to the backend through the official Gradio browser client.
+//
+// Why not a raw fetch to /gradio_api/call/<name>? On a ZeroGPU Space the Hub
+// hands the embedded app a per-visitor `X-IP-Token` JWT that identifies the
+// logged-in user (and their quota tier, e.g. PRO). The Gradio client forwards
+// that token on every queued call; a hand-rolled fetch does not, so the GPU
+// work gets billed to the anonymous IP pool and PRO users hit the 2-min/day
+// limit. Routing through Client.connect() restores correct quota attribution.
+// Pin the client version: an unpinned `@gradio/client` lets esm.sh serve a
+// moving "latest" (and its multi-file node-polyfill graph), so a fresh/broken
+// build or a single transient CDN fetch can fail the whole dynamic import with
+// "Failed to fetch dynamically imported module". 2.2.1 is the build that has
+// been working against this server's gradio 6.16.0 queue protocol.
+const GRADIO_CLIENT_URL = 'https://esm.sh/@gradio/client@2.2.1';
+let _gradioAppPromise = null;
+function getGradioApp() {
+  if (_gradioAppPromise === null) {
+    _gradioAppPromise = (async () => {
+      let lastErr;
+      for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+          const { Client } = await import(GRADIO_CLIENT_URL);
+          return await Client.connect(window.location.origin);
+        } catch (err) {
+          lastErr = err;
+          console.warn(`gradio client load attempt ${attempt}/3 failed:`, err);
+          await new Promise((r) => setTimeout(r, 500 * attempt));
+        }
+      }
+      // Don't cache the failure: a transient CDN/network blip would otherwise
+      // wedge the whole session (every later call returns this rejected promise)
+      // until a full page reload. Reset so the next user action retries.
+      _gradioAppPromise = null;
+      throw lastErr;
+    })();
+  }
+  return _gradioAppPromise;
+}
+
+async function callAPI(endpoint, payloadArray = []) {
+  try {
+    const app = await getGradioApp();
+    // predict() goes through Gradio's queue (with the X-IP-Token attached) and
+    // resolves once the call completes — including the GPU-bound `deliver`.
+    const result = await app.predict(`/${endpoint}`, payloadArray);
+    const data = result && result.data;
+    // Named endpoints return their outputs as an array: [returnValue].
+    if (Array.isArray(data) && data.length > 0) {
+      return data[0];
+    }
+    return data;
+  } catch (error) {
+    console.error(`API Error calling ${endpoint}:`, error);
+    return { success: false, error: error.message };
+  }
+}
+
+// Render the Guest Panel (Left Column)
+function renderVisitorsList(visitorsData) {
+  visitors = visitorsData || [];
+  visitorsList.innerHTML = '';
+  
+  if (visitors.length === 0 && (!gameState || gameState.total_stars >= 3)) {
+    visitorsList.innerHTML = '<p class="empty-state">No visitors left today.</p>';
+    return;
+  }
+  
+  visitors.forEach(visitor => {
+    const item = document.createElement('div');
+    const completedClass = visitor.completed ? 'completed' : '';
+    item.className = `visitor-item wobbly-border-sm shadow-offset ${completedClass} ${visitor.id === selectedVisitorId ? 'active' : ''}`;
+    
+    // Pick avatar character based on visitor name
+    let avatar = visitor.completed ? '✅' : '👤';
+    if (!visitor.completed) {
+      if (visitor.visitor.includes('Willow')) avatar = '🧓';
+      else if (visitor.visitor.includes('Witch')) avatar = '🧙‍♀️';
+      else if (visitor.visitor.includes('Goblin') || visitor.visitor.includes('Gremlin')) avatar = '👺';
+      else if (visitor.visitor.includes('Knight') || visitor.visitor.includes('Paladin')) avatar = '🛡️';
+      else if (visitor.visitor.includes('Elf') || visitor.visitor.includes('Fae')) avatar = '🧝';
+      else if (visitor.visitor.includes('Cat') || visitor.visitor.includes('Familiar')) avatar = '🐱';
+    }
+    
+    const displayPayment = (visitor.completed && visitor.actual_payment !== undefined && visitor.actual_payment !== null) 
+      ? visitor.actual_payment 
+      : visitor.base_payment;
+    
+    item.innerHTML = `
+      <div class="visitor-avatar wobbly-border-sm">${avatar}</div>
+      <div class="visitor-info">
+        <div class="visitor-name">${visitor.visitor}</div>
+        <div class="visitor-req-object">${visitor.completed ? 'delivered' : 'wants'}: <strong>${visitor.object}</strong></div>
+      </div>
+      <div class="visitor-reward">${displayPayment}g</div>
+    `;
+    
+    item.addEventListener('click', () => {
+      if (isDelivering) return;
+      selectVisitor(visitor.id);
+    });
+    
+    visitorsList.appendChild(item);
+  });
+  
+  // Render Locked Slots based on current stars
+  if (gameState && gameState.slot_unlock_stars) {
+    const totalStars = gameState.total_stars;
+    const unlockStars = gameState.slot_unlock_stars;
+    // Slot 3
+    if (unlockStars["3"] !== undefined && totalStars < unlockStars["3"]) {
+      renderLockedSlot(3, unlockStars["3"]);
+    }
+    // Slot 4
+    if (unlockStars["4"] !== undefined && totalStars < unlockStars["4"]) {
+      renderLockedSlot(4, unlockStars["4"]);
+    }
+  }
+}
+
+function renderLockedSlot(slotNum, reqStars) {
+  const item = document.createElement('div');
+  item.className = 'visitor-item locked wobbly-border-sm';
+  item.innerHTML = `
+    <div class="visitor-avatar wobbly-border-sm">🔒</div>
+    <div class="visitor-info">
+      <div class="visitor-name">Locked Slot ${slotNum}</div>
+      <div class="visitor-req-object">Requires ${reqStars} ⭐ to unlock</div>
+    </div>
+    <div class="visitor-reward">--g</div>
+  `;
+  visitorsList.appendChild(item);
+}
+
+
+// Select a visitor and render details (Center Column)
+function selectVisitor(visitorId) {
+  selectedVisitorId = visitorId;
+  
+  // Update active state in ledger
+  document.querySelectorAll('.visitor-item').forEach(el => el.classList.remove('active'));
+  const activeItem = visitors.find(v => v.id === visitorId);
+  
+  // Find visitor element in DOM
+  const visitorItems = visitorsList.children;
+  for (let i = 0; i < visitors.length; i++) {
+    if (visitors[i].id === visitorId) {
+      if (visitorItems[i]) visitorItems[i].classList.add('active');
+      break;
+    }
+  }
+  
+  if (!activeItem) {
+    visitorRequestCard.innerHTML = '<div class="card-loader">Select a guest from the ledger to begin crafting.</div>';
+    return;
+  }
+  
+  renderVisitorCard(activeItem);
+}
+
+// Render Detail Request Card (Message and Properties)
+function renderVisitorCard(visitor) {
+  // Determine if there are bonus properties (original length > 0)
+  const hasBonus = visitor.properties.length > 0;
+  let bonusSectionHtml = '';
+  
+  if (hasBonus) {
+    const bonusPropertiesHtml = visitor.properties.map((prop, idx) => {
+      let starSymbol = '☆';
+      
+      if (visitor.completed && visitor.breakdown && visitor.breakdown.passes) {
+        if (visitor.breakdown.passes[idx]) {
+          starSymbol = '★';
+        }
+      }
+      
+      return `
+        <div class="property-bullet">
+          <span class="bullet-star">${starSymbol}</span>
+          <div>
+            <strong>${prop.predicate}</strong>
+          </div>
+        </div>
+      `;
+    }).join('');
+    
+    bonusSectionHtml = `
+      <div class="request-properties-title">Bonus</div>
+      <div class="request-properties-list">
+        ${bonusPropertiesHtml}
+      </div>
+    `;
+  }
+
+  // Outcome/Breakdown box if completed
+  let outcomeBoxHtml = '';
+  if (visitor.completed && visitor.breakdown) {
+    const b = visitor.breakdown;
+    const statusClass = b.recognized ? 'success' : 'fail';
+    const headerText = b.recognized ? '✅ Transmutation Success!' : '❌  Transmutation Failed!';
+    
+    let breakdownRows = '';
+    if (b.recognized) {
+      if (visitor.properties.length > 0) {
+        const pct = Math.round(b.stars_earned * (b.star_multiplier || 0.2) * 100);
+        breakdownRows = `
+          <li><span>Base Payment:</span><strong>+${b.base_payment}g</strong></li>
+          <li><span>Bonus (+${pct}%):</span><strong>+${b.bonus_earned}g</strong></li>
+          <li class="total"><span>Total Gold Received:</span><strong>${b.total_payment}g</strong></li>
+        `;
+      } else {
+        breakdownRows = `
+          <li><span>Base Payment:</span><strong>+${b.base_payment}g</strong></li>
+          <li class="total"><span>Total Gold Received:</span><strong>${b.total_payment}g</strong></li>
+        `;
+      }
+    } else {
+      breakdownRows = `
+        <li><span>Base Payment (50%):</span><strong style="color:var(--color-error)">+${b.base_payment_earned}g</strong></li>
+        <li class="total"><span>Total Gold Received:</span><strong>${b.total_payment}g</strong></li>
+      `;
+    }
+    
+    outcomeBoxHtml = `
+      <div class="delivery-outcome-box ${statusClass}">
+        <h4>${headerText}</h4>
+        <ul class="breakdown-rows">
+          ${breakdownRows}
+        </ul>
+      </div>
+    `;
+  }
+
+  // Cross out details visually if completed
+  const completedStyle = visitor.completed ? 'style="opacity: 0.7;"' : '';
+  const strikethroughStyle = visitor.completed ? 'style="text-decoration: line-through;"' : '';
+
+  let doodleHtml = '';
+  // Prefer the generated image (image-gen second stage) over the raw doodle.
+  const deliveredImg = visitor.generated || visitor.doodle;
+  if (visitor.completed && deliveredImg) {
+    doodleHtml = `
+      <div class="delivered-doodle-container">
+        <img class="delivered-doodle-preview" src="${deliveredImg}" alt="Delivered Spell Image" />
+      </div>
+    `;
+  }
+
+  visitorRequestCard.innerHTML = `
+    <div ${completedStyle}>
+      <div class="request-meta">
+        <span class="request-visitor" ${strikethroughStyle}>${visitor.visitor}</span>
+        <span class="request-gold">${visitor.completed ? '💰 Received' : '💰 ' + visitor.base_payment + 'g'}</span>
+      </div>
+      <p class="request-flavor">"${visitor.flavor}"</p>
+      <div class="request-target">
+        Target: <strong style="color: var(--color-primary);" ${strikethroughStyle}>${visitor.object}</strong>
+      </div>
+      ${bonusSectionHtml}
+    </div>
+    ${doodleHtml}
+    ${outcomeBoxHtml}
+  `;
+
+  // Disable canvas action buttons if visitor is completed
+  if (visitor.completed) {
+    btnDeliver.disabled = true;
+    btnDeliver.innerHTML = 'Completed <span class="material-symbols-outlined">history_edu</span>';
+    btnReset.disabled = true;
+  } else if (gameState && gameState.status === 'playing') {
+    btnDeliver.disabled = false;
+    btnDeliver.innerHTML = 'Transmute <span class="material-symbols-outlined">history_edu</span>';
+    btnReset.disabled = false;
+  }
+}
+
+
+// Render structured payment breakdown on completion
+// Outcomes are now rendered inline inside the visitor card details.
+
+function appendTempLog(icon, text, className) {
+  const listDiv = outcomeContent.querySelector('.logs-list');
+  if (listDiv) {
+    const tempEntry = document.createElement('div');
+    tempEntry.className = `log-entry ${className}`;
+    tempEntry.innerHTML = `
+      <span class="log-icon">${icon}</span>
+      <span class="log-text">${text}</span>
+    `;
+    listDiv.appendChild(tempEntry);
+    const panel = document.getElementById('outcome-panel');
+    if (panel) {
+      panel.scrollTop = panel.scrollHeight;
+    }
+  } else {
+    outcomeContent.innerHTML = `<p class="empty-state">${text}</p>`;
+  }
+}
+
+function renderLogs(logs, status) {
+  if (!logs || logs.length === 0) {
+    outcomeContent.innerHTML = '<p class="empty-state">No actions logged yet.</p>';
+    return;
+  }
+  
+  let html = '<div class="logs-list">';
+  logs.forEach(log => {
+    let icon = '📝';
+    let className = 'log-generic';
+    
+    if (log.includes('Day ')) {
+      icon = '📅';
+      className = 'log-day-start';
+    } else if (log.includes('New customer ')) {
+      icon = '👤';
+      className = 'log-new-customer';
+    } else if (log.includes('Bought a ') && log.includes('Potion')) {
+      icon = '🧪';
+      className = 'log-shop';
+    } else if (log.includes('Crystal upgraded')) {
+      icon = '🔮';
+      className = 'log-shop';
+    } else if (log.includes('Successfully transmuted ')) {
+      icon = '✨';
+      className = 'log-delivery-success';
+    } else if (log.includes('Failed to transmute ')) {
+      icon = '⚠️';
+      className = 'log-delivery-fail';
+    } else if (log.includes('Paid ') && log.includes(' rent')) {
+      icon = '🌙';
+      className = 'log-rent-paid';
+    } else if (log.includes('Failed to pay rent')) {
+      icon = '💀';
+      className = 'log-rent-failed';
+    } else if (log.includes('Paid the remaining debt')) {
+      icon = '💸';
+      className = 'log-debt-paid';
+    } else if (log.includes('Failed to pay the debt')) {
+      icon = '💀';
+      className = 'log-debt-failed';
+    } 
+    
+    html += `
+      <div class="log-entry ${className}">
+        <span class="log-icon">${icon}</span>
+        <span class="log-text">${log}</span>
+      </div>
+    `;
+  });
+  
+  if (status !== 'playing') {
+    let isWon = status === 'won';
+    let endMsg = isWon ? '🤗 YOU WON!' : '😭 GAME OVER';
+    html += `
+      <div class="${isWon ? 'outcome-success' : 'outcome-fail'}" style="text-align:center; padding: 12px; margin-top: 10px;">
+        <h3 style="font-size: 16px; margin: 0;">${endMsg}</h3>
+        <p style="margin: 6px 0 0 0; font-style:italic; font-size: 11px;">Click 'New Run' to try again.</p>
+      </div>
+    `;
+  }
+  
+  html += '</div>';
+  outcomeContent.innerHTML = html;
+  
+  const panel = document.getElementById('outcome-panel');
+  if (panel) {
+    panel.scrollTop = panel.scrollHeight;
+  }
+}
+
+// Refresh General Game State HUD & Shop
+function refreshGameState(game) {
+  if (!game) return;
+  gameState = game;
+  
+  // Status panel
+  statDay.textContent = `${game.day} / ${game.deadline_day}`;
+  statGold.textContent = `${game.gold}g`;
+  statDebt.textContent = `${game.debt}g`;
+  statStars.textContent = `${game.total_stars}`;
+  
+  // Shop prices
+  costPotion.textContent = `${game.potion_price}g`;
+  costMaxMana.textContent = `${game.max_mana_price}g`;
+  
+  // Refresh mana bar
+  updateManaBar();
+  
+  // Render logs
+  renderLogs(game.logs, game.status);
+  
+  // Lock controls if game is won/lost (terminal)
+  if (game.status !== 'playing') {
+    btnDeliver.disabled = true;
+    btnReset.disabled = true;
+    btnBuyPotion.disabled = true;
+    btnBuyMax.disabled = true;
+    btnEndDay.disabled = true;
+  } else {
+    btnDeliver.disabled = false;
+    btnReset.disabled = false;
+    btnBuyPotion.disabled = false;
+    btnBuyMax.disabled = false;
+    btnEndDay.disabled = false;
+  }
+}
+
+// Button Click Interactions
+btnNewGame.addEventListener('click', async () => {
+  outcomeContent.innerHTML = '<p class="empty-state">Starting a new run...</p>';
+  clearCanvas();
+  spentMana = 0;
+  
+  const res = await callAPI('start_game');
+  if (res && res.success) {
+    refreshGameState(res.game);
+    renderVisitorsList(res.visitors);
+    if (res.selected_visitor_id) {
+      selectVisitor(res.selected_visitor_id);
+    } else {
+      selectedVisitorId = null;
+      visitorRequestCard.innerHTML = '<div class="card-loader">Select a guest from the ledger to begin crafting.</div>';
+    }
+  } else {
+    outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Failed to start game: ${res.error || 'Unknown error'}</p>`;
+  }
+});
+
+btnReset.addEventListener('click', async () => {
+  if (!gameState || gameState.status !== 'playing') return;
+
+  const res = await callAPI('reset_canvas', [spentMana]);
+  if (res && res.success) {
+    clearCanvas();
+    spentMana = 0;
+
+    // Hidden harness gesture: 5 consecutive Resets flip test mode on for this
+    // session (no off switch — refresh the page for a normal run). Count first so
+    // a UI-refresh hiccup can't swallow the click.
+    resetStreak += 1;
+    if (resetStreak >= 5) {
+      resetStreak = 0;
+      await enableTestMode();
+      return;
+    }
+    refreshGameState(res.game);
+  } else {
+    alert(res.error || 'Failed to reset canvas');
+  }
+});
+
+// Any press anywhere EXCEPT the Reset button breaks the consecutive-Reset gesture,
+// so the test-mode combo can't be triggered accidentally across other actions.
+// pointerdown (not click) so it also catches canvas draw-start and other drags;
+// closest('#btn-reset') because the press target is usually the button's icon span.
+document.addEventListener('pointerdown', (e) => {
+  if (!e.target.closest('#btn-reset')) resetStreak = 0;
+});
+
+// Start a fresh test-mode run (hidden 5-reset gesture). Mirrors btnNewGame, and
+// reveals the image-gen tuning panel (hidden during normal play).
+async function enableTestMode() {
+  const res = await callAPI('enable_testmode');
+  if (res && res.success) {
+    clearCanvas();
+    spentMana = 0;
+    const panel = document.getElementById('gen-tuning-panel');
+    if (panel) panel.style.display = '';
+    refreshGameState(res.game);
+    renderVisitorsList(res.visitors);
+    if (res.selected_visitor_id) {
+      selectVisitor(res.selected_visitor_id);
+    } else {
+      selectedVisitorId = null;
+    }
+    appendTempLog('🧪', res.message || 'Test mode enabled.', 'log-appraising');
+  }
+}
+
+// --- image-gen tuning panel -----------------------------------------------
+// The panel's default values are rendered into the HTML from the Python
+// constants by the server (get_index/_render_index) — the single source of
+// truth — so there is nothing to hydrate client-side. readGenOpts just sends
+// the current field values (incl. the editable style/negative text) on deliver.
+function readGenOpts() {
+  const $ = (id) => document.getElementById(id);
+  const num = (id, fallback) => {
+    const el = $(id);
+    const v = el ? parseFloat(el.value) : NaN;
+    return Number.isFinite(v) ? v : fallback;
+  };
+  const str = (id) => {
+    const el = $(id);
+    return el ? el.value : '';
+  };
+  const enableEl = $('gen-enable');
+  return {
+    enabled: enableEl ? enableEl.checked : false,
+    steps: num('gen-steps', 18),
+    guidance: num('gen-guidance', 5.0),
+    controlnet_scale: num('gen-cnet', 1.1),
+    seed: num('gen-seed', 0),
+    style_suffix: str('gen-style'),
+    base_negative: str('gen-negative'),
+  };
+}
+
+btnDeliver.addEventListener('click', async () => {
+  if (!gameState || gameState.status !== 'playing') return;
+  if (!selectedVisitorId) {
+    alert('Select a visitor from the ledger first!');
+    return;
+  }
+
+  // Extract canvas PNG data URL
+  const pngDataUrl = canvas.toDataURL('image/png');
+  
+  appendTempLog('⏳', 'Transmuting the glyph...', 'log-appraising');
+  
+  // Save state & elements
+  isDelivering = true;
+  drawing = false;
+  startBleedingEffect();
+  const originalHTML = btnDeliver.innerHTML;
+  btnDeliver.disabled = true;
+  btnDeliver.innerHTML = 'Transmuting <span class="material-symbols-outlined">history_edu</span>';
+  
+  // Disable guest items
+  document.querySelectorAll('.visitor-item').forEach(el => {
+    el.style.pointerEvents = 'none';
+    el.style.opacity = '0.6';
+  });
+  
+  // Disable End Day
+  btnEndDay.disabled = true;
+  
+  // Start mana bouncing
+  manaBarInner.classList.add('mana-bouncing');
+
+  let deliverySuccessful = false;
+  try {
+    const res = await callAPI('deliver', [pngDataUrl, spentMana, selectedVisitorId, JSON.stringify(readGenOpts())]);
+    if (res && res.success) {
+      deliverySuccessful = true;
+      stopBleedingEffect(true);
+      if (res.breakdown && res.breakdown.description) {
+        console.log(res.breakdown.description);
+      }
+      clearCanvas();
+      spentMana = 0;
+      refreshGameState(res.game);
+      renderVisitorsList(res.visitors);
+      // Outcomes are now displayed inline inside the selected completed guest card details
+      
+      // Select next visitor automatically if available
+      if (res.selected_visitor_id) {
+        selectVisitor(res.selected_visitor_id);
+      } else {
+        selectedVisitorId = null;
+        visitorRequestCard.innerHTML = '<div class="card-loader">No visitors remaining today. Click "End Day" to progress.</div>';
+      }
+    } else {
+      outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Appraisal error: ${res.error || 'Unknown error'}</p>`;
+    }
+  } catch (err) {
+    outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Appraisal error: ${err.message || err}</p>`;
+  } finally {
+    isDelivering = false;
+    stopBleedingEffect(deliverySuccessful);
+    
+    // Enable End Day (unless game state dictates otherwise, e.g. status !== 'playing')
+    if (gameState && gameState.status === 'playing') {
+      btnEndDay.disabled = false;
+    }
+    
+    // Re-enable and restore visitor items
+    document.querySelectorAll('.visitor-item').forEach(el => {
+      el.style.pointerEvents = '';
+      el.style.opacity = '';
+    });
+    
+    // Stop mana bouncing
+    manaBarInner.classList.remove('mana-bouncing');
+    updateManaBar();
+
+    // Restore deliver button text and disabled state based on the current selected visitor
+    const activeItem = selectedVisitorId ? visitors.find(v => v.id === selectedVisitorId) : null;
+    if (activeItem && activeItem.completed) {
+      btnDeliver.disabled = true;
+      btnDeliver.innerHTML = 'Completed <span class="material-symbols-outlined">history_edu</span>';
+    } else {
+      btnDeliver.innerHTML = originalHTML;
+      if (gameState && gameState.status === 'playing' && selectedVisitorId) {
+        btnDeliver.disabled = false;
+      } else {
+        btnDeliver.disabled = true;
+      }
+    }
+  }
+});
+
+btnBuyPotion.addEventListener('click', async () => {
+  if (!gameState || gameState.status !== 'playing') return;
+  
+  const res = await callAPI('buy_potion');
+  if (res && res.success) {
+    refreshGameState(res.game);
+  } else {
+    outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Cannot buy potion: ${res.error || 'Not enough gold'}</p>`;
+  }
+});
+
+btnBuyMax.addEventListener('click', async () => {
+  if (!gameState || gameState.status !== 'playing') return;
+  
+  const res = await callAPI('buy_max_mana');
+  if (res && res.success) {
+    refreshGameState(res.game);
+  } else {
+    outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Cannot upgrade max mana: ${res.error || 'Not enough gold'}</p>`;
+  }
+});
+
+btnEndDay.addEventListener('click', async () => {
+  if (!gameState || gameState.status !== 'playing') return;
+
+  appendTempLog('⏳', 'Paying rent and starting next day...', 'log-advancing');
+  clearCanvas();
+  spentMana = 0;
+  
+  const res = await callAPI('end_day');
+  if (res && res.success) {
+    refreshGameState(res.game);
+    renderVisitorsList(res.visitors);
+    
+    if (res.selected_visitor_id) {
+      selectVisitor(res.selected_visitor_id);
+    } else {
+      selectedVisitorId = null;
+      visitorRequestCard.innerHTML = '<div class="card-loader">No visitors today.</div>';
+    }
+  } else {
+    outcomeContent.innerHTML = `<p class="empty-state" style="color:var(--color-error)">Failed to end day: ${res.error || 'Unknown error'}</p>`;
+  }
+});
+
+// Instructions Modal Listeners
+btnInstructions.addEventListener('click', () => {
+  instructionsModal.classList.remove('hidden');
+});
+
+btnCloseInstructions.addEventListener('click', () => {
+  instructionsModal.classList.add('hidden');
+});
+
+instructionsModal.addEventListener('click', (e) => {
+  if (e.target === instructionsModal) {
+    instructionsModal.classList.add('hidden');
+  }
+});
+
+// Initialize game on load
+window.addEventListener('DOMContentLoaded', () => {
+  // Trigger New Game automatically on start
+  btnNewGame.click();
+});
+

witch_wood/ui/static/index.html

@@ -0,0 +1,234 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>🧙‍♀️ Inkwitch — Redesign</title>
+  
+  <!-- Font and Icon Imports -->
+  <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@600;700;800&family=Quicksand:wght@400;500;600&display=swap" rel="stylesheet"/>
+  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet"/>
+  
+  <!-- Custom Stylesheet with cache buster -->
+  <link rel="stylesheet" href="/static/style.css?v=22"/>
+</head>
+<body class="paper-texture">
+
+  <!-- Top Status Bar (Horizontal HUD) -->
+  <header class="status-bar wobbly-border shadow-offset">
+    <div class="status-bar-brand">
+      <h1 class="handwritten-brand">InkWitch</h1>
+      
+      <!-- Top Action Controls (Moved New Run here, added Instructions) -->
+      <div class="top-bar-actions">
+        <button id="btn-new-game" class="btn-sketch btn-warning btn-sm">
+          New Run <span class="material-symbols-outlined">restart_alt</span>
+        </button>
+        <button id="btn-instructions" class="btn-sketch btn-secondary btn-sm">
+          Instruction <span class="material-symbols-outlined">assignment</span>
+        </button>
+      </div>
+    </div>
+    
+    <div class="status-bar-items">
+      <div class="status-item-horizontal">
+        <span class="icon">📅</span>
+        <span class="stat-label">Day:</span>
+        <span id="stat-day" class="value">-/-</span>
+      </div>
+      <div class="status-item-horizontal">
+        <span class="icon">💰</span>
+        <span class="stat-label">Gold:</span>
+        <span id="stat-gold" class="value">--g</span>
+      </div>
+      <div class="status-item-horizontal">
+        <span class="icon">🔑</span>
+        <span class="stat-label">Rent:</span>
+        <span class="value">{{WW_RENT}}g</span>
+      </div>
+      <div class="status-item-horizontal">
+        <span class="icon">⚖️</span>
+        <span class="stat-label">Debt:</span>
+        <span id="stat-debt" class="value">--g</span>
+      </div>
+      <div class="status-item-horizontal">
+        <span class="icon">⭐</span>
+        <span class="stat-label">Reputation:</span>
+        <span id="stat-stars" class="value">--</span>
+      </div>
+    </div>
+  </header>
+
+  <!-- Main Panels Container (Distributed Horizontally) -->
+  <div class="workbench-panels">
+    
+    <!-- Left Column: Visitors & Request Ledger -->
+    <aside class="ledger-panel wobbly-border shadow-offset transform-left">
+      <div class="panel-header">
+        <h2 class="handwritten-title">Guest List</h2>
+        <p class="tagline">Today's active guests...</p>
+      </div>
+      
+      <!-- List of Today's Visitors -->
+      <div id="visitors-list" class="visitors-list">
+        <!-- Rendered dynamically in app.js -->
+        <p class="empty-state">No visitors left today.</p>
+      </div>
+
+      <hr class="ledger-divider"/>
+
+      <!-- Selected Visitor Card -->
+      <section id="visitor-request-card" class="visitor-request-card wobbly-border-sm paper-sheet">
+        <div class="card-loader">Select a guest from the ledger to begin crafting.</div>
+      </section>
+      
+    </aside>
+
+    <!-- Center Column: The Workbench & Canvas (Spacious drawing area) -->
+    <main class="canvas-panel wobbly-border shadow-offset">
+      
+      <!-- Central Drawing Area -->
+      <section class="drawing-area pencil-bg wobbly-border-sm">
+        
+        <!-- Mana Bar (Metered Progress) -->
+        <div class="mana-container">
+          <div class="mana-meta">
+            <span class="label">Mana</span>
+            <span id="mana-text" class="value">-- / --</span>
+          </div>
+          <div class="mana-bar-outer wobbly-border-sm">
+            <div id="mana-bar-inner" class="mana-bar-inner scribble-fill" style="width: 100%;"></div>
+          </div>
+        </div>
+
+        <!-- HTML5 Canvas -->
+        <div class="canvas-wrapper wobbly-border-sm">
+          <canvas id="paint-canvas" width="384" height="384"></canvas>
+        </div>
+
+        <!-- Workbench Action Buttons -->
+        <div class="workbench-actions">
+          <button id="btn-reset" class="btn-sketch btn-secondary">
+            <span class="material-symbols-outlined">mop</span> Reset
+          </button>
+          <button id="btn-deliver" class="btn-sketch btn-primary">
+            Transmute <span class="material-symbols-outlined">history_edu</span>
+          </button>
+        </div>
+
+      </section>
+
+    </main>
+
+    <!-- Right Column: Shop & Controls -->
+    <div class="right-column transform-right">
+      
+      <!-- End Day (Moved here, above shop) -->
+      <button id="btn-end-day" class="btn-sketch btn-danger">
+        End Day & Pay Rent <span class="material-symbols-outlined">bedtime</span>
+      </button>
+
+      <!-- image-gen tuning panel — hidden in normal play; revealed only after the
+           hidden test-mode gesture (app.js enableTestMode). Image-gen itself still
+           runs in normal play using the default params below. Default values are
+           injected from the Python constants by the server (get_index); do NOT
+           hardcode them here. -->
+      <section id="gen-tuning-panel" class="shop-panel wobbly-border shadow-offset" style="display:none;">
+        <h3 class="handwritten-title">🧪 Image-gen (temp)</h3>
+        <label style="display:flex; align-items:center; gap:8px; margin-bottom:8px;">
+          <input type="checkbox" id="gen-enable" {{WW_GEN_ENABLED_CHECKED}} /> Enable image generation
+        </label>
+        <label style="display:block; margin-bottom:6px;">
+          Steps <input type="number" id="gen-steps" value="{{WW_GEN_STEPS}}" min="1" max="50" step="1" style="width:70px;" />
+        </label>
+        <label style="display:block; margin-bottom:6px;">
+          Guidance <input type="number" id="gen-guidance" value="{{WW_GEN_GUIDANCE}}" min="1" max="15" step="0.5" style="width:70px;" />
+        </label>
+        <label style="display:block; margin-bottom:6px;">
+          ControlNet scale <input type="number" id="gen-cnet" value="{{WW_GEN_CNET_SCALE}}" min="0.1" max="1.5" step="0.05" style="width:70px;" />
+        </label>
+        <label style="display:block; margin-bottom:6px;">
+          Seed <input type="number" id="gen-seed" value="{{WW_GEN_SEED}}" min="0" step="1" style="width:90px;" />
+        </label>
+        <label style="display:block; margin-bottom:6px;">
+          Style suffix
+          <textarea id="gen-style" rows="3" style="width:100%; box-sizing:border-box; resize:vertical;">{{WW_STYLE_SUFFIX}}</textarea>
+        </label>
+        <label style="display:block;">
+          Base negative
+          <textarea id="gen-negative" rows="3" style="width:100%; box-sizing:border-box; resize:vertical;">{{WW_BASE_NEGATIVE}}</textarea>
+        </label>
+      </section>
+
+      <!-- Shop Panel (Only Goods) -->
+      <section class="shop-panel wobbly-border shadow-offset">
+        <h3 class="handwritten-title">Shop</h3>
+        <div class="upgrade-row">
+          <button id="btn-buy-potion" class="btn-sketch btn-shop">
+            <div class="shop-item-desc">
+              <span class="icon">🧪</span>
+              <div class="label-group">
+                <span class="item-name">Mana Potion</span>
+                <span class="item-benefit">+{{WW_POTION_MANA}} mana</span>
+              </div>
+            </div>
+            <span id="cost-potion" class="price">--g</span>
+          </button>
+          
+          <button id="btn-buy-max" class="btn-sketch btn-shop">
+            <div class="shop-item-desc">
+              <span class="icon">🔮</span>
+              <div class="label-group">
+                <span class="item-name">Crystal Upgrade</span>
+                <span class="item-benefit">+{{WW_MANA_UPGRADE_AMOUNT}} max mana</span>
+              </div>
+            </div>
+            <span id="cost-max-mana" class="price">--g</span>
+          </button>
+        </div>
+      </section>
+
+      <!-- Workbench Logs Card -->
+      <section id="outcome-panel" class="outcome-panel wobbly-border shadow-offset">
+        <h3 class="handwritten-title">Logbook</h3>
+        <div id="outcome-content" class="outcome-content">
+          <p class="empty-state">No actions logged yet.</p>
+        </div>
+      </section>
+
+    </div>
+
+  </div>
+
+  <!-- Instruction Modal (Hand-drawn instruction booklet) -->
+  <div id="instructions-modal" class="modal-overlay hidden">
+    <div class="modal-content wobbly-border shadow-offset paper-sheet">
+      <div class="modal-header">
+        <h3 class="handwritten-title">You Better Work, Witch</h3>
+        <button id="btn-close-instructions" class="btn-close">&times;</button>
+      </div>
+      <div class="modal-body">
+        <p style="margin-top: 6px; font-weight: 500;">
+          Dear Witch, your research funds are completely dried up, and your loan is due. To save my investment, I've converted your lab into a retail store. If you want to keep your roof and pay off your debt, you better get to work.
+        </p>
+        <p style="margin-top: 6px; font-weight: 500;">
+          Here is how we are going to run this store to get my money back:
+        </p>
+        <ul style="margin-top: 8px;">
+          <li><strong>Drawing</strong>: Draw a glyph of what the guests want on the canvas. Drawing drains your mana. No mana, no magic.</li>
+          <li><strong>Clean Slate</strong>: Resetting refunds <strong>{{WW_CANVAS_RESET_REFUND_PCT}}%</strong> of the mana spent on the current drawing.</li>
+          <li><strong>Transmutation</strong>: Transmute your glyph and sell your creation. Pass basic check to get base pay. Earn bonus gold for each matching quality.</li>
+          <li><strong>Shop</strong>: Buy potions to temporarily restore mana, or upgrade your crystal to permanently expand your maximum mana capacity.</li>
+          <li><strong>Daily Overhead</strong>: I will deduct <strong>{{WW_RENT}} gold rent</strong> each night. Pay the full <strong>{{WW_DEBT}} gold debt</strong> by Day {{WW_DEADLINE_DAY}} or you are bankrupt!</li>
+        </ul>
+        <p style="margin-top: 10px; font-style: italic; text-align: right; color: var(--color-secondary);">
+          — Golan, Zero Bank
+        </p>
+      </div>
+    </div>
+  </div>
+
+  <!-- JavaScript Entry Point with cache buster -->
+  <script src="/static/app.js?v=26"></script>
+</body>
+</html>

witch_wood/ui/static/style.css

@@ -0,0 +1,1134 @@
+/* style.css - Inkwitch Redesign Style Sheet */
+
+/* Global Colors & Design Tokens */
+:root {
+  --color-ink: #2c2825;          /* Charcoal Ink instead of harsh black */
+  --color-paper: #fffcf8;        /* Off-white paper background */
+  --color-desk: #ede6d9;         /* Muted desk color under the notebook */
+  --color-primary: #3d608e;      /* Primary Ink Blue */
+  --color-primary-light: #d8e6f5;/* Light Ink Blue background */
+  --color-secondary: #894d59;    /* Dusty Rose for accents / shop items */
+  --color-secondary-light: #ffd9df;
+  --color-success: #3a6836;      /* Forest Green for checks/wins */
+  --color-success-light: #e2f5df;
+  --color-warning: #b78a2a;      /* Antique Gold */
+  --color-warning-light: #fef4db;
+  --color-error: #ba1a1a;        /* Crimson */
+  --color-error-light: #ffdad6;
+  --color-card-bg: #ffffff;
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: 'Quicksand', sans-serif;
+  color: var(--color-ink);
+  background-color: var(--color-desk);
+  height: 100vh;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  overflow: hidden; /* Force everything to stay within viewport */
+}
+
+.paper-texture {
+  background-image: 
+    radial-gradient(#cabfad 1px, transparent 1px),
+    url("https://www.transparenttextures.com/patterns/natural-paper.png");
+  background-size: 30px 30px, auto;
+}
+
+/* Wobbly Border Utilities */
+.wobbly-border {
+  border: 2px solid var(--color-ink);
+  border-radius: 255px 25px 225px 25px/25px 225px 25px 255px;
+  position: relative;
+  background-color: var(--color-paper);
+}
+
+.wobbly-border-sm {
+  border: 2px solid var(--color-ink);
+  border-radius: 120px 12px 100px 12px/12px 100px 12px 120px;
+}
+
+/* Card Drop Offset Shadows (Tactile Stationery Style) */
+.shadow-offset {
+  box-shadow: 5px 5px 0px 0px var(--color-ink);
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+/* Top Horizontal Status Bar */
+.status-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 10px 24px;
+  background-color: var(--color-paper);
+  border-radius: 200px 15px 200px 15px/15px 200px 15px 200px;
+  height: 60px;
+  flex-shrink: 0;
+}
+
+.status-bar-brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.brand-icon {
+  font-size: 28px;
+  color: var(--color-primary);
+}
+
+.handwritten-brand {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 20px;
+  letter-spacing: -0.01em;
+}
+
+.status-bar-items {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.status-item-horizontal {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 700;
+  font-size: 16px;
+  padding: 4px 12px;
+  background-color: #ffffff;
+  border: 1px dashed rgba(44, 40, 37, 0.3);
+  border-radius: 6px;
+}
+
+.status-item-horizontal .icon {
+  font-size: 18px;
+}
+
+/* Layout Grid styling - distributed horizontally and viewport constrained */
+.workbench-panels {
+  display: grid;
+  grid-template-columns: 280px 1fr 300px;
+  gap: 20px;
+  flex-grow: 1;
+  height: calc(100vh - 108px); /* Remaining viewport height */
+  min-height: 0; /* Let grid items shrink properly */
+}
+
+/* Right Column Wrapper */
+.right-column {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* Panel Containers */
+.ledger-panel, .canvas-panel {
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  height: 100%;
+  overflow: hidden; /* Prevent panels from growing beyond the layout height */
+}
+
+.shop-panel {
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  flex-shrink: 0;
+}
+
+/* Rotating panels for organic sketch look */
+.transform-left {
+  transform: rotate(-0.5deg);
+}
+
+.transform-right {
+  transform: rotate(0.5deg);
+}
+
+/* Typography styles */
+.handwritten-title {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 20px;
+  line-height: 1.2;
+  border-bottom: 2px dashed rgba(44, 40, 37, 0.2);
+  padding-bottom: 4px;
+  margin-bottom: 2px;
+}
+
+.panel-header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex-shrink: 0;
+}
+
+.panel-header .header-icon {
+  font-size: 28px;
+  color: var(--color-primary);
+}
+
+.tagline {
+  font-size: 12px;
+  color: #666;
+  font-style: italic;
+}
+
+/* List of visitors (Left Panel) */
+.visitors-list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  overflow-y: auto;
+  flex-grow: 1;
+  padding-right: 4px;
+  max-height: 48%; /* Leave room for card details below */
+}
+
+.visitor-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px;
+  background-color: #ffffff;
+  cursor: pointer;
+  transition: transform 0.2s, background-color 0.2s;
+  flex-shrink: 0;
+}
+
+.visitor-item:hover {
+  transform: scale(1.02) rotate(1deg);
+  background-color: var(--color-primary-light);
+}
+
+.visitor-item.active {
+  background-color: var(--color-primary-light);
+  border-color: var(--color-primary);
+  box-shadow: 3px 3px 0px 0px var(--color-ink);
+}
+
+.visitor-item.completed {
+  background-color: #eae6db;
+  border-color: rgba(44, 40, 37, 0.2);
+  opacity: 0.8;
+}
+
+.visitor-item.completed:hover {
+  background-color: #dfdacd;
+}
+
+.visitor-item.completed.active {
+  background-color: var(--color-primary-light);
+  opacity: 1;
+}
+
+.visitor-item.completed .visitor-name {
+  text-decoration: line-through;
+  color: #777;
+}
+
+.visitor-item.completed .visitor-req-object {
+  color: #888;
+}
+
+.visitor-item.completed .visitor-reward {
+  color: var(--color-success);
+  font-weight: 800;
+}
+
+.visitor-item.locked {
+  background-color: #ede6d9;
+  border: 2px dashed rgba(44, 40, 37, 0.4);
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.visitor-item.locked:hover {
+  transform: none !important;
+  background-color: #ede6d9;
+  box-shadow: none !important;
+}
+
+.visitor-item.locked .visitor-name {
+  color: #888;
+  font-style: italic;
+  font-weight: 500;
+}
+
+.visitor-item.locked .visitor-req-object {
+  color: #999;
+}
+
+
+.visitor-avatar {
+  width: 38px;
+  height: 38px;
+  background-color: #ede6d9;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  font-size: 18px;
+  flex-shrink: 0;
+}
+
+.visitor-info {
+  flex-grow: 1;
+  min-width: 0; /* Allows ellipsis/truncation of child text */
+}
+
+.visitor-name {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 700;
+  font-size: 14px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.visitor-req-object {
+  font-size: 12px;
+  color: #555;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.visitor-reward {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 700;
+  font-size: 13px;
+  color: var(--color-warning);
+  flex-shrink: 0;
+}
+
+/* Selected Visitor Card (Center Panel) */
+.visitor-request-card {
+  padding: 12px 16px;
+  background-color: #fffde6; /* Sticky note yellow */
+  transform: rotate(-0.5deg);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex-shrink: 0;
+  max-height: 48%;
+  overflow-y: auto; /* Internal scrolling if properties lists get long */
+}
+
+.card-loader {
+  font-style: italic;
+  color: #666;
+  text-align: center;
+  padding: 6px;
+  font-size: 13px;
+}
+
+.request-meta {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  border-bottom: 1px dotted rgba(44, 40, 37, 0.3);
+  padding-bottom: 4px;
+}
+
+.request-visitor {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 16px;
+  color: var(--color-secondary);
+}
+
+.request-gold {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-warning);
+}
+
+.request-flavor {
+  font-size: 13px;
+  font-style: italic;
+  color: #555;
+  line-height: 1.3;
+}
+
+.request-target {
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.request-properties-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  color: #666;
+}
+
+.request-properties-list {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.property-bullet {
+  display: flex;
+  align-items: flex-start;
+  gap: 6px;
+  font-size: 13px;
+}
+
+.bullet-star {
+  color: var(--color-primary);
+  font-size: 14px;
+  margin-top: 1px;
+}
+
+.property-predicate {
+  font-size: 11px;
+  color: #666;
+  font-style: italic;
+}
+
+/* Delivered Doodle styling */
+.delivered-doodle-container {
+  margin-top: 10px;
+  padding: 0;
+  border: 2px dashed var(--color-ink);
+  border-radius: 8px;
+  background-color: #ffffff;
+  box-shadow: 2px 2px 0px 0px rgba(0,0,0,0.15);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  box-sizing: border-box;
+}
+
+.delivered-doodle-preview {
+  width: 100%;
+  height: auto;
+  display: block;
+  border-radius: 6px;
+}
+
+/* Drawing Workbench Section */
+.drawing-area {
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  flex-grow: 1;
+  justify-content: center;
+  min-height: 0;
+}
+
+/* Mana Indicator */
+.mana-container {
+  width: 100%;
+  max-width: 384px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex-shrink: 0;
+}
+
+.mana-meta {
+  display: flex;
+  justify-content: space-between;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.mana-meta .label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #666;
+}
+
+.mana-meta .value {
+  font-family: monospace;
+  font-weight: bold;
+}
+
+.mana-bar-outer {
+  height: 12px;
+  background-color: #ffffff;
+  overflow: hidden;
+  padding: 1px;
+}
+
+.mana-bar-inner {
+  height: 100%;
+  background-color: var(--color-primary);
+  border-radius: 6px;
+  transition: width 0.1s ease-out;
+}
+
+/* Scribble Texture for Mana Fill */
+@keyframes scribble {
+  0% { transform: skewX(-3deg) translateY(0); }
+  50% { transform: skewX(3deg) translateY(0.5px); }
+  100% { transform: skewX(-3deg) translateY(0); }
+}
+
+.scribble-fill {
+  background-image: repeating-linear-gradient(45deg, rgba(255,255,255,0.15), rgba(255,255,255,0.15) 2px, transparent 2px, transparent 4px);
+  animation: scribble 0.3s infinite ease-in-out;
+}
+
+.mana-bouncing {
+  width: 30% !important;
+  animation: scribble 0.3s infinite ease-in-out, mana-ping-pong 1.5s infinite ease-in-out !important;
+}
+
+@keyframes mana-ping-pong {
+  0% { margin-left: 0%; }
+  50% { margin-left: 70%; }
+  100% { margin-left: 0%; }
+}
+
+/* HTML5 Canvas styles */
+.canvas-wrapper {
+  background-color: #ffffff;
+  display: inline-block;
+  padding: 2px;
+  flex-shrink: 1;
+  min-height: 0;
+}
+
+#paint-canvas {
+  display: block;
+  background-color: #ffffff;
+  touch-action: none;
+  cursor: crosshair;
+  max-height: 100%;
+  max-width: 100%;
+}
+
+.canvas-wrapper.wobbly-border-sm {
+  border-radius: 8px;
+}
+
+/* Action Buttons */
+.workbench-actions {
+  display: flex;
+  gap: 12px;
+  width: 100%;
+  max-width: 384px;
+  flex-shrink: 0;
+}
+
+.btn-sketch {
+  flex-grow: 1;
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 700;
+  font-size: 14px;
+  padding: 10px 14px;
+  border: 2px solid var(--color-ink);
+  background-color: #ffffff;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  box-shadow: 3px 3px 0px 0px var(--color-ink);
+  transition: transform 0.1s, box-shadow 0.1s;
+}
+
+/* Wobbly shape definitions for buttons */
+.btn-sketch {
+  border-radius: 80px 10px 90px 10px/10px 90px 10px 80px;
+}
+
+.btn-sketch:hover {
+  transform: translate(-1px, -1px) rotate(-0.5deg);
+  box-shadow: 4px 4px 0px 0px var(--color-ink);
+}
+
+.btn-sketch:active {
+  transform: translate(2px, 2px);
+  box-shadow: 1px 1px 0px 0px var(--color-ink);
+}
+
+.btn-primary {
+  background-color: var(--color-primary-light);
+  color: var(--color-primary);
+  font-size: 15px;
+  font-weight: 800;
+}
+
+.btn-primary:hover {
+  background-color: #c5dcfa;
+}
+
+.btn-secondary {
+  color: #555;
+}
+
+.btn-danger {
+  background-color: var(--color-error-light);
+  color: var(--color-error);
+}
+
+.btn-danger:hover {
+  background-color: #ffc2bb;
+}
+
+.btn-warning {
+  background-color: var(--color-warning-light);
+  color: var(--color-warning);
+}
+
+.btn-warning:hover {
+  background-color: #fcebbb;
+}
+
+/* Right Panel: Shop, Controls & Outcomes */
+
+/* Shop Upgrades Shelf */
+.shop-upgrades {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.upgrade-row {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.btn-shop {
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  text-align: left;
+  border-radius: 120px 10px 100px 10px/10px 100px 10px 120px;
+}
+
+.shop-item-desc {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.shop-item-desc .icon {
+  font-size: 20px;
+}
+
+.label-group {
+  display: flex;
+  flex-direction: column;
+}
+
+.item-name {
+  font-weight: bold;
+  font-size: 13px;
+}
+
+.item-benefit {
+  font-size: 10px;
+  color: #666;
+  font-style: italic;
+}
+
+.btn-shop .price {
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 14px;
+  color: var(--color-warning);
+  background-color: #ffffff;
+  padding: 2px 6px;
+  border: 1px solid var(--color-ink);
+  border-radius: 4px;
+}
+
+/* Control actions bottom */
+.control-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+/* Outcome Panel (Right Panel bottom) */
+.outcome-panel {
+  padding: 12px;
+  background-color: var(--color-paper);
+  transform: rotate(-0.5deg);
+  flex-grow: 1;
+  overflow-y: auto; /* Internal scrolling */
+  min-height: 100px;
+}
+
+.outcome-content {
+  font-size: 13px;
+  line-height: 1.3;
+}
+
+.outcome-success {
+  background-color: var(--color-success-light);
+  border: 1.5px solid var(--color-success);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.outcome-success h3 {
+  color: var(--color-success);
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-size: 14px;
+  margin-bottom: 2px;
+}
+
+.outcome-fail {
+  background-color: var(--color-error-light);
+  border: 1.5px solid var(--color-error);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.outcome-fail h3 {
+  color: var(--color-error);
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-size: 14px;
+  margin-bottom: 2px;
+}
+
+.outcome-message {
+  font-style: italic;
+  font-size: 12px;
+  color: #555;
+  margin-bottom: 6px;
+}
+
+.breakdown-list {
+  list-style: none;
+  padding-left: 2px;
+  margin-top: 4px;
+  border-top: 1px dashed rgba(44, 40, 37, 0.2);
+  padding-top: 4px;
+  font-size: 11px;
+}
+
+.breakdown-list li {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 2px;
+}
+
+.breakdown-list li.total {
+  font-weight: bold;
+  font-size: 12px;
+  border-top: 1px dotted rgba(44, 40, 37, 0.4);
+  padding-top: 2px;
+  margin-top: 2px;
+  color: var(--color-ink);
+}
+
+.empty-state {
+  text-align: center;
+  color: #777;
+  font-style: italic;
+  font-size: 12px;
+  margin-top: 12px;
+}
+
+/* Decorative Doodles */
+.decorative-doodle {
+  position: absolute;
+  pointer-events: none;
+  opacity: 0.12;
+  color: var(--color-ink);
+}
+
+.doodle-left {
+  bottom: 8px;
+  right: 8px;
+  transform: rotate(15deg);
+}
+
+.doodle-right {
+  bottom: 8px;
+  left: 8px;
+  transform: rotate(-15deg);
+}
+
+.doodle-left .material-symbols-outlined,
+.doodle-right .material-symbols-outlined {
+  font-size: 48px;
+}
+
+/* Custom ruled sheets */
+.paper-sheet {
+  background-image: linear-gradient(rgba(44, 40, 37, 0.08) 1px, transparent 1px);
+  background-size: 100% 20px;
+  line-height: 20px;
+}
+
+/* Responsive Scaling for smaller heights / widths */
+@media (max-width: 1000px) {
+  body {
+    height: auto;
+    overflow: auto;
+  }
+  .workbench-panels {
+    grid-template-columns: 1fr;
+    height: auto;
+  }
+  .status-bar {
+    border-radius: 12px;
+    height: auto;
+    flex-direction: column;
+    gap: 12px;
+    padding: 12px;
+  }
+  .status-bar-items {
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 12px;
+  }
+  .ledger-panel, .canvas-panel {
+    transform: none !important;
+    height: auto;
+    min-height: auto;
+  }
+  .right-column {
+    height: auto;
+    overflow: auto;
+  }
+}
+
+/* Delivery Outcome Box inside Request Card details */
+.delivery-outcome-box {
+  margin-top: 10px;
+  padding: 12px;
+  border: 2px dashed var(--color-ink);
+  border-radius: 8px;
+  font-size: 13px;
+  line-height: 1.4;
+  background-color: #ffffff;
+  box-shadow: 2px 2px 0px 0px rgba(0,0,0,0.15);
+}
+
+.delivery-outcome-box.success {
+  border-color: var(--color-success);
+  background-color: var(--color-success-light);
+}
+
+.delivery-outcome-box.success h4 {
+  color: var(--color-success);
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 14px;
+  margin-bottom: 4px;
+}
+
+.delivery-outcome-box.fail {
+  border-color: var(--color-error);
+  background-color: var(--color-error-light);
+}
+
+.delivery-outcome-box.fail h4 {
+  color: var(--color-error);
+  font-family: 'Bricolage Grotesque', sans-serif;
+  font-weight: 800;
+  font-size: 14px;
+  margin-bottom: 4px;
+}
+
+.delivery-outcome-box .outcome-desc {
+  font-style: italic;
+  color: #555;
+  margin-bottom: 8px;
+}
+
+.delivery-outcome-box .breakdown-rows {
+  list-style: none;
+  border-top: 1px dotted rgba(44, 40, 37, 0.2);
+  padding-top: 6px;
+  margin-top: 6px;
+  font-size: 12px;
+}
+
+.delivery-outcome-box .breakdown-rows li {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 3px;
+}
+
+.delivery-outcome-box .breakdown-rows li.total {
+  font-weight: bold;
+  font-size: 13px;
+  border-top: 1px dotted var(--color-ink);
+  padding-top: 4px;
+  margin-top: 4px;
+  color: var(--color-ink);
+}
+
+/* Button & Top Bar layout helpers */
+.btn-block {
+  width: 100%;
+  flex-shrink: 0;
+  flex-grow: 0 !important;
+}
+
+.btn-sm {
+  padding: 6px 10px !important;
+  font-size: 11px !important;
+  box-shadow: 2px 2px 0px 0px var(--color-ink) !important;
+}
+
+.btn-sm:active {
+  transform: translate(1px, 1px) !important;
+  box-shadow: 1px 1px 0px 0px var(--color-ink) !important;
+}
+
+.top-bar-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-left: 14px;
+}
+
+/* Instruction Modal overlay/card styling */
+.modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  background-color: rgba(44, 40, 37, 0.45);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  z-index: 2000;
+  backdrop-filter: blur(2px);
+  transition: opacity 0.2s ease;
+}
+
+.modal-overlay.hidden {
+  display: none !important;
+  pointer-events: none;
+}
+
+.modal-content {
+  background-color: var(--color-paper);
+  padding: 24px;
+  max-width: 520px;
+  width: 90%;
+  position: relative;
+  border-radius: 15px 15px 15px 15px/15px 15px 15px 15px;
+  animation: modal-enter 0.25s cubic-bezier(0.175, 0.885, 0.32, 1.275);
+}
+
+@keyframes modal-enter {
+  from { transform: scale(0.9) translateY(20px); opacity: 0; }
+  to { transform: scale(1) translateY(0); opacity: 1; }
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  border-bottom: 2px dashed rgba(44, 40, 37, 0.2);
+  padding-bottom: 8px;
+  margin-bottom: 12px;
+}
+
+.modal-header .handwritten-title {
+  border-bottom: none;
+  margin-bottom: 0;
+  padding-bottom: 0;
+}
+
+.btn-close {
+  background: none;
+  border: none;
+  font-size: 28px;
+  cursor: pointer;
+  color: var(--color-ink);
+  line-height: 1;
+  padding: 0 4px;
+}
+
+.btn-close:hover {
+  color: var(--color-secondary);
+}
+
+.modal-body {
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.modal-body p {
+  margin-bottom: 8px;
+}
+
+.modal-body ul {
+  list-style: none;
+  padding-left: 0;
+}
+
+.modal-body li {
+  margin-bottom: 8px;
+  padding-left: 18px;
+  position: relative;
+}
+
+.modal-body li::before {
+  content: "✦";
+  position: absolute;
+  left: 2px;
+  color: var(--color-primary);
+  font-size: 12px;
+}
+
+/* End Day Button Refinement */
+#btn-end-day {
+  width: calc(100% - 32px);
+  margin: 8px 16px 4px 16px;
+  padding: 10px 20px;
+  flex-grow: 0 !important;
+  flex-shrink: 0;
+}
+
+/* Stat Label & New Run Button Styling refinements */
+.stat-label {
+  font-size: 11px;
+  color: #666;
+  text-transform: uppercase;
+  font-family: 'Quicksand', sans-serif;
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  margin-right: 4px;
+}
+
+#btn-new-game {
+  font-size: 13px !important;
+  padding: 6px 12px !important;
+}
+
+/* Ledger Panel Divider */
+.ledger-divider {
+  border: none;
+  border-top: 2px dashed rgba(44, 40, 37, 0.25);
+  margin: 4px 0;
+  flex-shrink: 0;
+}
+
+/* Logs styling */
+.logs-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 4px;
+}
+
+.log-entry {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 6px 8px;
+  border-bottom: 1px dotted rgba(44, 40, 37, 0.15);
+  font-size: 13px;
+  line-height: 1.4;
+  color: var(--color-ink);
+  background: rgba(255, 255, 255, 0.4);
+  border-radius: 4px;
+  transition: background-color 0.2s ease;
+}
+
+.log-entry:hover {
+  background: rgba(255, 255, 255, 0.85);
+}
+
+.log-icon {
+  font-size: 16px;
+  flex-shrink: 0;
+  margin-top: 1px;
+}
+
+.log-text {
+  flex-grow: 1;
+}
+
+/* Custom log type highlight styles */
+.log-day-start {
+  font-weight: 700;
+  border-bottom: 1.5px solid rgba(44, 40, 37, 0.3);
+  background: var(--color-warning-light);
+}
+
+.log-new-customer {
+  border-left: 3px solid var(--color-secondary);
+}
+
+.log-shop {
+  border-left: 3px solid #6b5b95;
+}
+
+.log-delivery-success {
+  border-left: 3px solid var(--color-success);
+  background: var(--color-success-light);
+}
+
+.log-delivery-fail {
+  border-left: 3px solid var(--color-error);
+  background: var(--color-error-light);
+}
+
+.log-rent-paid {
+  border-left: 3px solid #feb236;
+}
+
+.log-rent-failed {
+  border-left: 3px solid var(--color-error);
+  font-weight: bold;
+}
+
+.log-debt-paid {
+  border-left: 3px solid var(--color-success);
+  font-weight: bold;
+}
+
+.log-game-won {
+  background: var(--color-success-light);
+  border: 2px dashed var(--color-success);
+  font-weight: bold;
+  font-size: 14px;
+  padding: 10px;
+}
+
+.log-game-lost {
+  background: var(--color-error-light);
+  border: 2px dashed var(--color-error);
+  font-weight: bold;
+  font-size: 14px;
+  padding: 10px;
+}
+
+.log-appraising, .log-advancing {
+  font-style: italic;
+  color: #777;
+  border-left: 3px dashed var(--color-ink);
+  background: rgba(255, 255, 255, 0.25);
+}
+

witch_wood/vision/__init__.py

@@ -0,0 +1,3 @@
+from witch_wood.vision.mock import MockBackend
+
+__all__ = ["MockBackend"]

witch_wood/vision/base.py

@@ -0,0 +1,16 @@
+"""VisionBackend protocol: appraise a doodle against a request."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from witch_wood.core.schema import Request, Verdict
+
+
+class VisionBackend(Protocol):
+    def appraise(self, image, request: Request) -> Verdict:
+        """Return raw (un-thresholded) recognition + per-property confidences."""
+        ...
+
+    def check_properties(self, image, request: Request) -> tuple[float, ...]:
+        """Per-property confidences for `image` (e.g. a generated render)."""
+        ...

witch_wood/vision/minicpm.py

@@ -0,0 +1,361 @@
+"""MiniCPM-V backend (ZeroGPU-ready).
+
+Scoring uses TWO categorical (yes/no) turns in ONE conversation, because
+MiniCPM-V cannot emit calibrated float confidences and degrades in combined
+float prompts:
+
+  Turn 1 — recognition + description: "Does it depict a {object}?" (yes/no, the
+           gate) plus a one-sentence free-form description of the doodle.
+  Turn 2 — properties: one combined numbered yes/no block, ALWAYS run (even if
+           recognition is "no"). It reuses the same conversation, so the image
+           and the turn-1 description stay in context to ground the answers.
+
+yes -> 1.0, no -> 0.0. The prompt builders and parsers are pure/testable.
+
+ZeroGPU notes: the model/processor are loaded once at module scope (registered
+for ZeroGPU device migration) and the whole appraisal — every `generate` call
+for one doodle — runs inside a single `@spaces.GPU` entry. The model lives in a
+module global, so it is never pickled across the worker-process boundary; only
+the PIL image, the `Request` dataclass, and the returned `Verdict` cross it.
+"""
+from __future__ import annotations
+
+import re
+
+import spaces
+import torch
+
+from witch_wood.core.schema import Property, Request, Verdict
+
+MODEL_ID = "openbmb/MiniCPM-V-4.6"
+
+# Diagnostic free-form prompt used by scripts/model_spike.py --describe.
+DESCRIBE_PROMPT = (
+    "This is a rough black-and-white line-drawing doodle. "
+    "First name the single object you think it most depicts in 1-3 words. "
+    "Then briefly describe its overall shape and the distinct parts you can see. "
+    "Do not refuse; give your best guess even if the drawing is crude."
+)
+
+
+def recognition_prompt(request: Request) -> str:
+    """Call-1 prompt: recognition gate (yes/no) + a one-sentence description."""
+    return (
+        "Look at this rough black-and-white line drawing.\n"
+        f"1) Does it depict a {request.object}? Answer yes or no.\n"
+        "2) In one short sentence, describe the object and its visible parts.\n"
+        "Reply in exactly this format:\n"
+        "MATCH: <yes or no>\n"
+        "DESCRIPTION: <one sentence>"
+    )
+
+
+def properties_prompt(request: Request) -> str:
+    """Call-2 prompt: one combined numbered yes/no block over all properties."""
+    lines = "\n".join(
+        f"{i + 1}. {p.predicate}" for i, p in enumerate(request.properties)
+    )
+    return "For the same drawing, answer yes or no for each:\n" + lines
+
+
+def property_prompt_single(prop: Property) -> str:
+    """Separate-mode prompt: ask yes/no about ONE property of the same drawing."""
+    return (
+        "For the same drawing, answer with a single word, yes or no:\n"
+        f"{prop.predicate}"
+    )
+
+
+def property_prompt_render(prop: Property) -> str:
+    """Yes/no prompt for checking ONE property on a GENERATED photo (not a doodle).
+
+    Used by the score-the-render stage: each property is a standalone turn on the
+    polished image, with no doodle/'drawing' framing."""
+    return (
+        "Look at this image and answer with a single word, yes or no:\n"
+        f"{prop.predicate}"
+    )
+
+
+def _yes(text: str) -> float:
+    """1.0 if an affirmative 'yes' token appears, else 0.0."""
+    return 1.0 if re.search(r"\byes\b", text, re.IGNORECASE) else 0.0
+
+
+def parse_recognition(text: str) -> tuple[float, str]:
+    """Parse a MATCH/DESCRIPTION reply into (recognition_conf, description).
+
+    Falls back to scanning the first line for yes if the MATCH label is absent.
+    """
+    m = re.search(r"MATCH:\s*(.+)", text, re.IGNORECASE)
+    d = re.search(r"DESCRIPTION:\s*(.+)", text, re.IGNORECASE | re.DOTALL)
+    description = d.group(1).strip() if d else ""
+    if m:
+        recognition = _yes(m.group(1))
+    else:
+        first_line = text.splitlines()[0] if text.strip() else ""
+        recognition = _yes(first_line)
+    return recognition, description
+
+
+def parse_properties(text: str, n_props: int) -> tuple[float, ...]:
+    """Parse numbered yes/no lines into n_props confidences (missing -> 0.0)."""
+    answers: dict[int, float] = {}
+    for line in text.splitlines():
+        m = re.match(r"\s*(\d+)[.):]\s*(.*)", line)
+        if m:
+            answers[int(m.group(1))] = _yes(m.group(2))
+    if answers:
+        return tuple(answers.get(i + 1, 0.0) for i in range(n_props))
+    # Fallback: take bare yes/no tokens in order.
+    tokens = re.findall(r"\b(yes|no)\b", text, re.IGNORECASE)
+    vals = [1.0 if t.lower() == "yes" else 0.0 for t in tokens]
+    return tuple(vals[i] if i < len(vals) else 0.0 for i in range(n_props))
+
+
+# --- Model loading (module scope, ZeroGPU-registered) -----------------------
+
+_MODEL = None
+_PROCESSOR = None
+
+
+def _ensure_loaded():
+    """Load MiniCPM-V once into module globals.
+
+    On ZeroGPU `import spaces` monkey-patches torch so `device_map="auto"` at
+    module scope registers the weights for device migration; the real GPU is
+    only attached inside the `@spaces.GPU` call that runs generation.
+    """
+    global _MODEL, _PROCESSOR
+    if _MODEL is None:
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+
+        _PROCESSOR = AutoProcessor.from_pretrained(MODEL_ID)
+        _MODEL = AutoModelForImageTextToText.from_pretrained(
+            MODEL_ID, torch_dtype="auto", device_map="auto"
+        )
+    return _MODEL, _PROCESSOR
+
+
+# Trigger the (slow) load eagerly at import so the cold-start cost is paid once
+# at Space startup rather than on the first player's delivery.
+_ensure_loaded()
+
+
+# --- Generation helpers (run inside the @spaces.GPU worker) ------------------
+
+def _text(content: str) -> dict:
+    return {"role": "user", "content": [{"type": "text", "text": content}]}
+
+
+def _image_text(image, content: str) -> dict:
+    return {"role": "user", "content": [
+        {"type": "image", "image": image},
+        {"type": "text", "text": content},
+    ]}
+
+
+def _run_fresh(model, processor, messages: list[dict], max_new_tokens: int):
+    """Template + generate one turn; return (text, cache, full_token_seq)."""
+    inputs = processor.apply_chat_template(
+        messages, tokenize=True, add_generation_prompt=True,
+        return_dict=True, return_tensors="pt",
+    ).to(model.device)
+    out = model.generate(
+        **inputs, max_new_tokens=max_new_tokens, do_sample=False,
+        return_dict_in_generate=True, use_cache=True,
+    )
+    seq = out.sequences
+    text = processor.batch_decode(
+        seq[:, inputs.input_ids.shape[1]:],
+        skip_special_tokens=True, clean_up_tokenization_spaces=False,
+    )[0]
+    return text, out.past_key_values, seq
+
+
+def _run(model, processor, messages: list[dict], max_new_tokens: int) -> str:
+    """Text-only convenience wrapper over _run_fresh (no cache reuse)."""
+    return _run_fresh(model, processor, messages, max_new_tokens)[0]
+
+
+def _run_cached(model, processor, full_messages, cache, prefix_seq, max_new_tokens) -> str:
+    """Generate one property turn reusing the recognition KV cache.
+
+    Finds the longest common prefix between the recognition token sequence
+    (prefix_seq) and the re-templated full conversation, crops the cache to
+    that boundary (the image tokens live inside it, so they are reused), and
+    feeds the remaining tokens. Crops back to the same boundary afterward so
+    the next property branches off a clean recognition-only prefix.
+    """
+    full = processor.apply_chat_template(
+        full_messages, tokenize=True, add_generation_prompt=True,
+        return_dict=True, return_tensors="pt",
+    ).to(model.device)
+    full_ids = full.input_ids
+    min_len = min(prefix_seq.shape[1], full_ids.shape[1])
+    diverge = (prefix_seq[0, :min_len] != full_ids[0, :min_len]).nonzero()
+    common = int(diverge[0].item()) if diverge.numel() else min_len
+    keep = min(common, cache.get_seq_length())
+    cache.crop(keep)
+    new_ids = full_ids[:, keep:]
+    attn = torch.ones((1, full_ids.shape[1]), dtype=torch.long,
+                      device=full_ids.device)
+    gen = model.generate(
+        input_ids=new_ids, attention_mask=attn, past_key_values=cache,
+        max_new_tokens=max_new_tokens, do_sample=False, use_cache=True,
+    )
+    text = processor.batch_decode(
+        gen[:, new_ids.shape[1]:],
+        skip_special_tokens=True, clean_up_tokenization_spaces=False,
+    )[0]
+    cache.crop(keep)  # restore shared prefix so the next property is isolated
+    return text
+
+
+def _appraise(model, processor, image, request: Request, use_kv_cache: bool) -> Verdict:
+    """Full two-call yes/no appraisal. Runs entirely on the GPU worker."""
+    from witch_wood.core import constants as C
+
+    rec_messages = [_image_text(image, recognition_prompt(request))]
+    rec_text, cache, rec_seq = _run_fresh(model, processor, rec_messages, max_new_tokens=80)
+    recognition, description = parse_recognition(rec_text)
+
+    assistant_turn = {"role": "assistant",
+                      "content": [{"type": "text", "text": rec_text}]}
+
+    def _property_turn(extra_user_msg, max_new_tokens, use_cache):
+        convo = [_image_text(image, recognition_prompt(request)),
+                 assistant_turn, extra_user_msg]
+        if use_cache:
+            return _run_cached(model, processor, convo, cache, rec_seq, max_new_tokens)
+        return _run(model, processor, convo, max_new_tokens)
+
+    if not request.properties:
+        properties = ()
+    elif C.SEPARATE_PROPERTY_CHECKS:
+        confs = []
+        for prop in request.properties:
+            # Cache reuse is safe + worthwhile here: the recognition prefix is
+            # reused across N short yes/no answers, which are robust to the tiny
+            # KV FP noise the cache introduces.
+            text = _property_turn(_text(property_prompt_single(prop)),
+                                  16, use_cache=use_kv_cache)
+            confs.append(_yes(text))
+        properties = tuple(confs)
+    else:
+        # Batch: ALWAYS re-template, never cache. A single combined call gets no
+        # amortization, and greedy decoding over its long answer diverges from
+        # the fresh-prefill output under cache FP noise (measured: verbose drift
+        # on ~half of tier-3 batch cases -> wrong stars). Caching is an
+        # optimization for the multi-call separate path only.
+        prop_text = _property_turn(_text(properties_prompt(request)),
+                                   64, use_cache=False)
+        properties = parse_properties(prop_text, len(request.properties))
+
+    return Verdict(
+        recognition=recognition, properties=properties, description=description
+    )
+
+
+def _appraise_duration(image, request: Request, use_kv_cache: bool = True) -> int:
+    """Estimate GPU seconds for the quota pre-check.
+
+    The appraisal is one ~80-token recognition generate plus one short yes/no
+    generate per property; a warm tier-0 call measured ~3s. Keep this small so
+    the quota pre-check doesn't block low-quota visitors (ZeroGPU reserves the
+    full declared duration up front and ranks shorter durations higher in the
+    queue), while leaving headroom for cold-start weight streaming."""
+    return 20 + 10 * len(request.properties)
+
+
+@spaces.GPU(duration=_appraise_duration)
+def appraise_gpu(image, request: Request, use_kv_cache: bool) -> Verdict:
+    """ZeroGPU entry point: one GPU acquisition per doodle appraisal.
+
+    The model lives in a module global (never pickled); only `image`/`request`
+    cross into the worker and a plain `Verdict` dataclass crosses back out.
+    """
+    model, processor = _ensure_loaded()
+    return _appraise(model, processor, image, request, use_kv_cache)
+
+
+# --- Property re-check on the generated render ------------------------------
+# The score-the-render stage: after the image-gen step, re-ask each property as
+# a standalone yes/no on the polished image (separate GPU acquisition — the
+# render doesn't exist until generation has run).
+
+def _check_properties(
+    model, processor, image, request: Request, doodle_passes=None
+) -> tuple[float, ...]:
+    """Per-property yes/no on a generated render.
+
+    `doodle_passes` (one bool per property, from the doodle appraisal) lets us
+    skip work: a property that PASSED on the doodle is trusted to carry through
+    the render and is scored 1.0 without a model call; only doodle-FAILED
+    properties are re-asked on the render (the generator may have added one
+    back). `doodle_passes=None` re-checks every property (legacy contract).
+
+    The re-checked properties share one render encoding: the first is a fresh
+    prefill, the rest reuse its KV cache (same trick as the doodle appraisal's
+    separate path) — the image + the fixed render instruction are the shared
+    prefix, only the predicate diverges, so the render is encoded once."""
+    props = request.properties
+    if not props:
+        return ()
+    if doodle_passes is None:
+        recheck_idx = list(range(len(props)))
+    else:
+        recheck_idx = [i for i in range(len(props)) if not doodle_passes[i]]
+
+    confs = [1.0] * len(props)            # passed props default to 1.0 (no call)
+    cache = seq = None
+    for n, i in enumerate(recheck_idx):
+        convo = [_image_text(image, property_prompt_render(props[i]))]
+        if n == 0:
+            text, cache, seq = _run_fresh(model, processor, convo, 16)
+        else:
+            text = _run_cached(model, processor, convo, cache, seq, 16)
+        confs[i] = _yes(text)
+    print(f"[recheck] rechecked {len(recheck_idx)} of {len(props)} props",
+          flush=True)
+    return tuple(confs)
+
+
+def _check_props_duration(image, request: Request) -> int:
+    return 15 + 8 * len(request.properties)
+
+
+@spaces.GPU(duration=_check_props_duration)
+def check_properties_gpu(image, request: Request) -> tuple[float, ...]:
+    model, processor = _ensure_loaded()
+    return _check_properties(model, processor, image, request)
+
+
+class MiniCPMBackend:
+    """Loads MiniCPM-V-4.6 and appraises doodles with the two-call yes/no flow.
+
+    The heavy model is a module global; this object only carries the cheap
+    `use_kv_cache` flag so it stays trivially picklable across the ZeroGPU
+    worker boundary.
+    """
+
+    def __init__(self, use_kv_cache: bool = False):
+        self._use_kv_cache = use_kv_cache
+        _ensure_loaded()
+
+    def appraise(self, image, request: Request) -> Verdict:
+        return appraise_gpu(image, request, self._use_kv_cache)
+
+    def check_properties(self, image, request: Request) -> tuple[float, ...]:
+        """Per-property yes/no on a generated render (the score-the-render step)."""
+        return check_properties_gpu(image, request)
+
+    def describe(self, image, question: str | None = None) -> str:
+        """Free-form: ask the model what it sees (diagnostic, not scored)."""
+        return _describe_gpu(image, question or DESCRIBE_PROMPT)
+
+
+@spaces.GPU(duration=60)
+def _describe_gpu(image, prompt_text: str) -> str:
+    model, processor = _ensure_loaded()
+    return _run(model, processor, [_image_text(image, prompt_text)], 200)

witch_wood/vision/mock.py

@@ -0,0 +1,34 @@
+"""MockBackend: scripted or seeded verdicts — no model, for dev and tests."""
+from __future__ import annotations
+
+import random
+
+from witch_wood.core.schema import Request, Verdict
+
+
+class MockBackend:
+    def __init__(self, seed: int = 0, scripted: list[Verdict] | None = None):
+        self._rng = random.Random(seed)
+        self._scripted = list(scripted) if scripted else None
+        self._i = 0
+
+    def appraise(self, image, request: Request) -> Verdict:
+        if self._scripted:
+            v = self._scripted[self._i % len(self._scripted)]
+            self._i += 1
+            return v
+        import os
+        if os.environ.get("WITCH_WOOD_MOCK_ALWAYS_PASS") == "1":
+            return Verdict(
+                recognition=1.0,
+                properties=tuple(1.0 for _ in request.properties),
+                description=f"a perfect mock doodle of a {request.object}",
+            )
+        return Verdict(
+            recognition=self._rng.random(),
+            properties=tuple(self._rng.random() for _ in request.properties),
+            description=f"a mock doodle of a {request.object}",
+        )
+
+    def check_properties(self, image, request: Request) -> tuple[float, ...]:
+        return self.appraise(image, request).properties