pythonhere 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

pythonhere/magic_here/prompts/jnius.md

@@ -0,0 +1,432 @@
+## Pyjnius
+
+`jnius` is installed.
+
+Rules:
+
+- Import Java classes with `from jnius import autoclass`.
+- For Java callbacks/listeners implemented in Python, import and use
+  `PythonJavaClass` and `java_method`. A plain Python class with a matching
+  method name is not a Java interface implementation.
+- Import `cast` only when the generated code actually uses it.
+- Do not import Android app classes directly from `jnius`. For example, do not
+  write `from jnius import PythonService`; use
+  `autoclass("org.kivy.android.PythonService")` inside the fallback path.
+- Import optional Android classes, such as `org.kivy.android.PythonService`,
+  only inside the fallback path where they are needed.
+- Use `cast` only when a Java API requires a specific declared type.
+- Keep Java object references local unless the user needs to inspect them later.
+- Convert Java strings to Python strings with `str(...)` before storing results.
+- Treat Java arrays and lists defensively: they may be `None`; iterate only after
+  checking.
+- Java arrays are Python-indexable in Pyjnius. Use `len(java_array)` and
+  `java_array[index]`. Do not call `.size()` or `.get()` unless the object is a
+  Java `List`.
+- For Java long bitmasks, Python `int` values are acceptable.
+- Catch narrow exceptions only around optional Android fields or deprecated APIs.
+  Do not hide collection-wide failures.
+- If catching an exception for one package/item, store a readable error string in
+  that item and continue.
+- Do not use Pyjnius to launch external processes.
+- Do not reference Android class constants from a variable that has not been
+  assigned with `autoclass`.
+
+Pyjnius arrays:
+- Use Python lists, bytes, or bytearray for Java array arguments.
+- Do not invent imports like `jarray`.
+- If a Java API needs a writable output buffer, use a mutable Python list or bytearray and check the method’s return value.
+
+Pyjnius object conversion rules:
+
+- Do not assume Python string conversion of Java objects produces valid Android
+  values.
+- Convert Java `String` objects to Python strings with `str(...)` before storing
+  ordinary text results, but do not use Python `str(...)` for Android object
+  identifiers that have their own Java string form, such as `Uri`.
+- For Java objects with Android-specific string forms, call the Java method
+  `toString()`.
+- For `android.net.Uri`, prefer keeping the Java `Uri` object and passing it
+  directly to Android APIs such as `ContentResolver.openInputStream(uri)`.
+- Do not convert Java `android.net.Uri` objects with Python `str(uri)`.
+  In Pyjnius, `str(uri)` may produce a Python object representation like
+  `<android.net.Uri at 0x... jclass=android/net/Uri ...>` instead of a valid
+  `content://...` URI string.
+- If a Java `Uri` must be stored as text, use `uri.toString()`, not `str(uri)`.
+- Never parse a Pyjnius object representation as a URI.
+- Any generated code that logs or displays a URI should log both the media ID
+  and `uri.toString()`, not the Python object representation.
+
+Wrong:
+
+```python
+content_uri = ContentUris.withAppendedId(ImagesMedia.EXTERNAL_CONTENT_URI, image_id)
+photos.append({"id": image_id, "uri": str(content_uri)})
+
+uri = Uri.parse(photo["uri"])
+stream = resolver.openInputStream(uri)
+```
+
+Correct, preferred:
+
+```python
+content_uri = ContentUris.withAppendedId(ImagesMedia.EXTERNAL_CONTENT_URI, image_id)
+photos.append({"id": image_id, "uri": content_uri})
+
+stream = resolver.openInputStream(photo["uri"])
+```
+
+Correct, if serialization is needed:
+
+```python
+content_uri = ContentUris.withAppendedId(ImagesMedia.EXTERNAL_CONTENT_URI, image_id)
+photos.append({"id": image_id, "uri": content_uri.toString()})
+
+Uri = autoclass("android.net.Uri")
+uri = Uri.parse(photo["uri"])
+stream = resolver.openInputStream(uri)
+```
+
+Pyjnius Java class access rules:
+
+- Do not call Java classes through undefined Python package names.
+- Every Java class used must be bound with `autoclass(...)`.
+- Do not assume Java package names are available as Python modules.
+
+Wrong:
+
+```python
+android.graphics.Bitmap.createScaledBitmap(bitmap, new_w, new_h, True)
+```
+
+Correct:
+
+```python
+Bitmap = autoclass("android.graphics.Bitmap")
+scaled_bitmap = Bitmap.createScaledBitmap(bitmap, new_w, new_h, True)
+```
+
+Nested Java classes:
+
+- In Pyjnius, nested Java classes must be imported with `$` using `autoclass`.
+  Do not access nested Java classes as Python attributes of the parent class.
+
+Correct:
+
+```python
+VERSION = autoclass("android.os.Build$VERSION")
+BitmapFactoryOptions = autoclass("android.graphics.BitmapFactory$Options")
+CompressFormat = autoclass("android.graphics.Bitmap$CompressFormat")
+PackageInfoFlags = autoclass("android.content.pm.PackageManager$PackageInfoFlags")
+ImagesMedia = autoclass("android.provider.MediaStore$Images$Media")
+```
+
+Incorrect:
+
+```python
+Build.VERSION.SDK_INT
+BitmapFactory.Options()
+Bitmap.CompressFormat
+PackageManager.PackageInfoFlags
+MediaStore.Images.Media
+```
+
+Android version checks:
+
+- Use:
+
+```python
+VERSION = autoclass("android.os.Build$VERSION")
+SDK_INT = VERSION.SDK_INT
+```
+
+- Do not use:
+
+```python
+Build.VERSION.SDK_INT
+```
+
+because Pyjnius does not reliably expose nested classes as Python attributes.
+
+Nullable Java constants:
+
+- Treat Android Java class constants returned through Pyjnius as nullable.
+  Some constants may be `None` even when the Android API normally defines them.
+- Never pass unchecked Pyjnius constants into Android APIs that expect strings,
+  arrays of strings, column names, permissions, selection clauses, sort orders,
+  file modes, or intent actions.
+- Before using a Java string constant in `projection`, `selection`, `sortOrder`,
+  `getColumnIndex(...)`, `Intent(...)`, or permission checks, resolve it to a
+  non-null Python string.
+
+Correct:
+
+```python
+ImagesMedia = autoclass("android.provider.MediaStore$Images$Media")
+
+COL_ID = ImagesMedia._ID or "_id"
+COL_DATE_ADDED = ImagesMedia.DATE_ADDED or "date_added"
+COL_DATE_TAKEN = ImagesMedia.DATE_TAKEN or "datetaken"
+COL_DISPLAY_NAME = ImagesMedia.DISPLAY_NAME or "_display_name"
+COL_BUCKET = ImagesMedia.BUCKET_DISPLAY_NAME or "bucket_display_name"
+
+projection = [COL_ID, COL_DATE_ADDED]
+sort_order = COL_DATE_ADDED + " DESC"
+```
+
+Incorrect:
+
+```python
+projection = [ImagesMedia._ID, ImagesMedia.DATE_TAKEN]
+sort_order = f"{ImagesMedia.DATE_TAKEN} DESC"
+selection = ImagesMedia.BUCKET_DISPLAY_NAME + " = ?"
+```
+
+- Never allow `None` inside Java `String[]` arguments or string parameters.
+  This includes MediaStore projections, selection args, sort order strings, and
+  cursor column names.
+- If an Android API throws a Java `NullPointerException` mentioning
+  `String.toLowerCase()` during a query, suspect a `None` column name or string
+  argument passed from Pyjnius.
+- Prefer explicit fallback strings for well-known Android column names rather
+  than raw constants when generating resilient code.
+
+Bitmap-related Pyjnius rules:
+
+- For bitmap decode options, use:
+
+```python
+BitmapFactoryOptions = autoclass("android.graphics.BitmapFactory$Options")
+opts = BitmapFactoryOptions()
+```
+
+- Never use:
+
+```python
+opts = BitmapFactory.Options()
+```
+
+- For bitmap compression format, use:
+
+```python
+CompressFormat = autoclass("android.graphics.Bitmap$CompressFormat")
+bitmap.compress(CompressFormat.JPEG, 85, output_stream)
+```
+
+- Never use:
+
+```python
+Bitmap.CompressFormat.JPEG
+```
+
+
+Android MediaStore and shared-media Pyjnius rules:
+
+- Prefer MediaStore content URIs over raw filesystem paths.
+- Do not depend on the `_data` column for gallery/media access.
+- Query `_id`, build a content URI, then decode through `ContentResolver`.
+- Keep the Java `Uri` object directly or store URI text with `uri.toString()`.
+  Do not store `str(uri)`.
+- Do not filter only by `bucket_display_name = "Camera"` unless the user
+  specifically asked for the Camera folder only. For a general gallery, query
+  all images first, then add filters only after the broad query is confirmed
+  working.
+- Always handle `cursor is None` and `cursor.getCount() == 0`.
+- Always close the cursor in `finally`.
+- If a thumbnail decode fails for one item, store/log a readable item-level
+  error and continue with other items.
+
+Preferred MediaStore URI pattern:
+
+```python
+ContentUris = autoclass("android.content.ContentUris")
+ImagesMedia = autoclass("android.provider.MediaStore$Images$Media")
+BitmapFactory = autoclass("android.graphics.BitmapFactory")
+BitmapFactoryOptions = autoclass("android.graphics.BitmapFactory$Options")
+
+content_uri = ContentUris.withAppendedId(
+    ImagesMedia.EXTERNAL_CONTENT_URI,
+    image_id,
+)
+
+opts = BitmapFactoryOptions()
+stream = resolver.openInputStream(content_uri)
+try:
+    bitmap = BitmapFactory.decodeStream(stream, None, opts)
+finally:
+    if stream is not None:
+        stream.close()
+```
+
+Avoid as the default:
+
+```python
+path = cursor.getString(cursor.getColumnIndex("_data"))
+bitmap = BitmapFactory.decodeFile(path, opts)
+```
+
+Android media permission and special-access rules:
+
+- Declaring a permission in `buildozer.spec` or `AndroidManifest.xml` does not
+  prove it is granted at runtime.
+- For Android 13+ image access, check/request
+  `android.permission.READ_MEDIA_IMAGES`.
+- For Android 13+ video access, check/request
+  `android.permission.READ_MEDIA_VIDEO`.
+- For Android 13+ audio access, check/request
+  `android.permission.READ_MEDIA_AUDIO`.
+- For Android 12 and below, check/request
+  `android.permission.READ_EXTERNAL_STORAGE`.
+- Do not rely on `WRITE_EXTERNAL_STORAGE` for reading shared photos on modern
+  Android.
+- Do not check `MANAGE_EXTERNAL_STORAGE` with `check_permission(...)`.
+  It is special Android settings access, not a normal runtime permission.
+- For arbitrary `/sdcard`, `/sdcard/DCIM`, `/sdcard/Download`, or full
+  shared-storage browsing on Android 11+, check
+  `Environment.isExternalStorageManager()`.
+- If all-files access is needed and not enabled, open
+  `Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION` with
+  `Uri.parse("package:" + activity.getPackageName())`. If that fails, fall back
+  to `Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION`.
+
+Thumbnail and cache rules:
+
+- Write generated thumbnails into the app cache directory from
+  `context.getCacheDir().getAbsolutePath()`.
+- Do not use `Path.cwd() / "gallery_cache"` for Android cache files.
+- Kivy `Image.source` should point to a real cache file path.
+- Do not assume Kivy supports `data:image/...;base64,...` sources.
+- Use separate constants for UI size and bitmap decode size, for example
+  `THUMB_UI_DP = dp(120)` and `THUMB_PX = 240`.
+- Do not pass `dp(...)` floats into Android bitmap APIs.
+- Android bitmap dimensions and sample sizes must be plain Python `int` values.
+- Recycle Android `Bitmap` objects after thumbnail compression when possible.
+
+Media/gallery error-reporting rules:
+
+- Do not hide media/gallery failures behind generic messages like
+  `Error loading photos. Check logs.`
+- Generated code should show the real failure stage and exception message in the
+  UI during development.
+- Background workers should return structured results such as
+  `{ "ok": False, "stage": "decode_thumbnail", "error": "AttributeError: ..." }`.
+- Logs may include full stack traces, but logs must not be the only place where
+  the real problem appears.
+
+General forbidden Pyjnius patterns:
+
+Never generate:
+
+```python
+BitmapFactory.Options()
+Bitmap.CompressFormat
+Build.VERSION
+MediaStore.Images.Media
+PackageManager.PackageInfoFlags
+projection = [SomeJavaClass.SOME_COLUMN]
+sort_order = f"{SomeJavaClass.SOME_COLUMN} DESC"
+```
+
+Generate:
+
+```python
+BitmapFactoryOptions = autoclass("android.graphics.BitmapFactory$Options")
+CompressFormat = autoclass("android.graphics.Bitmap$CompressFormat")
+VERSION = autoclass("android.os.Build$VERSION")
+ImagesMedia = autoclass("android.provider.MediaStore$Images$Media")
+PackageInfoFlags = autoclass("android.content.pm.PackageManager$PackageInfoFlags")
+
+COL = SomeJavaClass.SOME_COLUMN or "known_fallback_name"
+projection = [COL]
+sort_order = COL + " DESC"
+```
+
+For Android package APIs:
+
+- `PackageManager.GET_PERMISSIONS` requests permission metadata.
+- Android API 33 and newer require
+  `android.content.pm.PackageManager$PackageInfoFlags.of(flags)`.
+- In Pyjnius, define:
+
+```python
+PackageInfoFlags = autoclass("android.content.pm.PackageManager$PackageInfoFlags")
+```
+
+and call:
+
+```python
+PackageInfoFlags.of(flags)
+```
+
+- Do not access it as:
+
+```python
+PackageManager.PackageInfoFlags
+```
+
+- Older APIs accept integer flags.
+- System-app flags come from `android.content.pm.ApplicationInfo`.
+  Use `ApplicationInfo.FLAG_SYSTEM` and `ApplicationInfo.FLAG_UPDATED_SYSTEM_APP`.
+  Do not use `android.content.pm.ActivityInfo` for this.
+- Permission grant status comes from
+  `android.content.pm.PackageInfo.REQUESTED_PERMISSION_GRANTED`, not from
+  `PackageManager.PERMISSION_GRANTED` and not from `ActivityInfo`.
+- If checking requested permission grant status, define:
+
+```python
+PackageInfo = autoclass("android.content.pm.PackageInfo")
+```
+
+before using that constant.
+- Version code should use `longVersionCode` when present and fall back to
+  `versionCode`.
+
+Additional forbidden Pyjnius media patterns:
+
+Never generate:
+
+```python
+str(content_uri)
+Uri.parse(str(content_uri))
+photos.append({"uri": str(content_uri)})
+android.graphics.Bitmap.createScaledBitmap(bitmap, new_w, new_h, True)
+Path.cwd() / "gallery_cache"
+show_error("Error loading photos. Check logs.")
+return None  # after catching a media/gallery exception
+cursor.getString(cursor.getColumnIndex("_data"))  # as the primary media access path
+```
+
+Generate:
+
+```python
+photos.append({"uri": content_uri})
+# or, only if text serialization is required:
+photos.append({"uri": content_uri.toString()})
+
+Bitmap = autoclass("android.graphics.Bitmap")
+scaled_bitmap = Bitmap.createScaledBitmap(bitmap, new_w, new_h, True)
+
+cache_dir = context.getCacheDir().getAbsolutePath()
+
+return {
+    "ok": False,
+    "stage": stage,
+    "error": f"{type(e).__name__}: {e}",
+}
+```
+
+Pyjnius overload and Android intent safety:
+- When Java APIs have overloaded constructors or methods, prefer the least
+  ambiguous call pattern through Pyjnius. For Android `Intent`, create
+  `intent = Intent(action)` and then call setters such as `setData(...)`,
+  `setType(...)`, or `putExtra(...)` rather than relying on overloaded
+  constructors.
+- Do not pass Python `None` where Android expects a Java `String`, `String[]`,
+  `Uri`, `Intent`, `Context`, or callback/listener.
+- When an API expects a Java primitive array or Java collection, prefer normal
+  Python lists only when Pyjnius is known to convert them for that method.
+  Otherwise use the Android/Python-for-Android helper API if one exists.
+- For nullable Android constants, resolve to non-null Python strings before
+  passing them into Android APIs.
+- Keep Settings/Intent launch results in a named global and report whether
+  `startActivity(...)` was attempted; do not claim the requested setting changed
+  just because the Settings screen opened.

pythonhere/magic_here/prompts/kivy-kv.md

@@ -0,0 +1,239 @@
+## Kv design
+
+Use KV for layout only:
+- widget tree
+- ids
+- simple widget properties
+- simple canvas instructions
+
+Critical generated-KV constraints:
+- If KV uses `dp(...)` or `sp(...)`, the KV string must include the matching
+  `#:import` line once at the top, before widget rules.
+- If KV uses `sin(...)`, `cos(...)`, `abs(...)`, `min(...)`, or any other helper
+  function in an expression, the name must be defined in KV parser scope with
+  `#:import` or the calculation must be moved into Python.
+- Do not use KV dynamic class/template syntax such as `<Name@BaseWidget>:` in
+  generated PythonHere snippets.
+- Do not call `Builder.template(...)`; use `ui = Builder.load_string(KV)`.
+- Do not put callbacks in KV. Bind callbacks in Python after
+  `Builder.load_string(KV)`.
+- Do not use `app.some_method()` or `root.some_method()` in KV callbacks.
+- Do not use `#:set` to inject Python globals, callback functions, generated
+  text, or state into KV. Set widget properties and bind callbacks from Python
+  after loading.
+
+For generated PythonHere cells, do not put Python callbacks in KV.
+Do not put generated dynamic Python logic in KV.
+
+Avoid:
+`on_release: something()`
+`on_press: something()`
+`on_text: something(self.text)`
+`on_value: something(self.value)`
+`values: [f"{num}: {name}" for num, name in sorted(items.items())]`
+`text: some_python_variable`
+`source: compute_path()`
+`angle: app.feature_angle`
+
+Also avoid generated proxy/global calls in KV:
+`on_release: actions.handle(...)`
+`on_release: app_actions["handle"]()`
+`on_release: app.stop_everything()`
+`on_release: root.stop_everything()`
+`on_release: start_cb()`
+`text: app_poem_text`
+`#:set start_cb some_python_function`
+`#:set app_poem_text some_python_text`
+
+Avoid referencing notebook/global variables from KV. Kivy Builder may not have
+the expected globals in parser scope, and KV parser errors are hard to recover
+from in a live app. Put dynamic values into widgets from Python after the widget
+tree exists.
+Do not use `app.some_feature_state` in generated KV. In PythonHere, `app` is the
+real PythonHere Kivy App instance, not a generated feature controller. Store
+feature state on the generated root/widget class with Kivy properties, or update
+widget/canvas instructions from Python.
+
+Preferred pattern:
+- Put ids on interactive widgets in KV.
+- Load the UI.
+- Set dynamic properties from Python after `Builder.load_string(KV)`.
+- Bind callbacks in Python after `Builder.load_string(KV)`.
+
+Example:
+
+`ui = Builder.load_string(KV)`
+`ui.ids.primary_button.bind(on_release=handle_primary_action)`
+`ui.ids.value_slider.bind(value=handle_value_change)`
+
+Dynamic values example:
+
+```
+KV = """
+BoxLayout:
+    Spinner:
+        id: instrument_spinner
+        text: "Choose instrument"
+        values: []
+    Slider:
+        id: volume_slider
+"""
+
+ui = Builder.load_string(KV)
+ui.ids.instrument_spinner.values = [
+    f"{num}: {name}" for num, name in sorted(midi_instruments.items())
+]
+ui.ids.instrument_spinner.bind(text=handle_instrument)
+ui.ids.volume_slider.bind(value=handle_volume)
+```
+
+Widget-owned property example:
+
+```
+from kivy.properties import NumericProperty
+from kivy.uix.floatlayout import FloatLayout
+
+class DynamicRoot(FloatLayout):
+    feature_angle = NumericProperty(0)
+
+KV = """
+#:import dp kivy.metrics.dp
+
+<DynamicRoot>:
+    canvas.before:
+        PushMatrix:
+        Rotate:
+            angle: root.feature_angle
+            origin: self.center
+        Ellipse:
+            size: dp(120), dp(120)
+            pos: self.center_x - dp(60), self.center_y - dp(60)
+        PopMatrix:
+
+DynamicRoot:
+"""
+
+ui = Builder.load_string(KV)
+Clock.schedule_interval(lambda dt: setattr(ui, "feature_angle", ui.feature_angle + 3), 1 / 30)
+```
+
+KV root rule:
+- In PythonHere generated cells, `KV` must end with a concrete root widget instance.
+- Prefer a direct root widget such as `BoxLayout:`, `FloatLayout:`, `GridLayout:`, or a custom class instance such as `DesktopUI:`.
+- Do not make `KV` contain only class/rule definitions.
+- Do not use KV dynamic class/template syntax such as `<RootWidget@BoxLayout>:`
+  for generated PythonHere snippets.
+- Do not call `Builder.template(...)`. Use `ui = Builder.load_string(KV)` with a
+  KV string that ends in a concrete root widget instance.
+- Do not load rule-only KV and then instantiate a Python class manually, such as
+  `Builder.load_string(KV); ui = MyWidget()`. The generated KV should return the
+  actual root widget from `Builder.load_string(KV)`.
+- Do not call `Builder.unload_file(...)` or pass a fake `filename=...` for
+  generated inline KV snippets.
+
+Good:
+
+```
+KV = """
+BoxLayout:
+    Label:
+        text: "Hello"
+"""
+```
+
+Good when using custom classes:
+
+```
+KV = """
+<DesktopUI>:
+    ...
+
+DesktopUI:
+"""
+```
+
+Bad:
+
+```
+KV = """
+<DesktopUI>:
+    ...
+"""
+```
+
+because `Builder.load_string(KV)` returns `None` for rule-only KV.
+
+Required self-check:
+- If the code does `ui = Builder.load_string(KV)`, then `ui` must be a widget.
+- If `KV` contains `<SomeClass>:` rules, it must also contain a final concrete instance like `SomeClass:`.
+- Never call `root.add_widget(ui)` unless `ui is not None`.
+- Never call `Builder.template(...)` for generated PythonHere UI snippets.
+- Never define `<SomeName@BaseWidget>:` dynamic classes in generated KV.
+- Never use `#:set` to expose Python functions or generated text to KV.
+- Never call `Builder.unload_file(...)` for generated inline KV snippets.
+- If code defines a `KV = """..."""` string for the UI, it must actually load
+  that string with `Builder.load_string(KV)` and add the loaded widget, or omit
+  the KV string entirely. Do not define KV and then instantiate a bare Python
+  widget class such as `ui = MyWidget()`; that ignores the KV tree and usually
+  shows an empty UI.
+
+Kivy property compatibility:
+- Generated Kivy code must use only valid property option values in both KV and Python-created widgets. For `Label.shorten_from`, use only `"left"`, `"center"`, or `"right"`.
+
+KV imports:
+- Any Python name used inside KV expressions must either be a KV local such as
+  `self`, `root`, or an explicitly imported name declared with `#:import` at
+  the top of the KV string.
+- Do not assume Python imports outside the KV string are visible to the KV
+  parser. `from math import sin` in Python does not make `sin(...)` valid inside
+  KV; use `#:import sin math.sin` in the KV string or move the calculation into
+  Python.
+- If KV uses `dp(...)` or `sp(...)`, include exactly one matching import at the
+  top of the KV string:
+  `#:import dp kivy.metrics.dp`
+  `#:import sp kivy.metrics.sp`
+- If KV expressions use math functions, include explicit imports such as:
+  `#:import sin math.sin`
+  `#:import cos math.cos`
+- Do not generate duplicate `#:import` lines for the same name.
+- Prefer moving nontrivial calculations into Python properties or Python-side
+  canvas updates instead of putting complex formulas in KV. This is especially
+  important for animated positions, trigonometry, paths, query results, and
+  generated lists.
+- If a KV canvas expression still uses trigonometry, the KV string must include
+  the math imports once, before any widget rules:
+
+```
+KV = """
+#:import sin math.sin
+#:import cos math.cos
+#:import dp kivy.metrics.dp
+
+FloatLayout:
+    canvas:
+        Ellipse:
+            size: dp(24), dp(24)
+            pos: self.x + self.width * sin(root.phase), self.y
+"""
+```
+
+- Before returning code, scan the KV string for function calls such as `sin(`,
+  `cos(`, `dp(`, `sp(`, `rgba(`, or helper names and ensure each helper is
+  defined in KV parser scope or removed.
+
+KV safety additions:
+- `ids` exist on the loaded root widget, not as global variables. Access them as
+  `ui.ids.some_id` after `Builder.load_string(KV)` returns a concrete root
+  widget.
+- Avoid assigning duplicate ids in generated KV.
+- Do not create dynamic styling aliases such as `<PoemLabel@Label>:`. For
+  generated snippets, repeat simple properties, use a real Python class, or set
+  properties from Python after loading the widget tree.
+- Keep KV expressions literal and simple. Use Python to compute all lists,
+  paths, formatted labels, colors derived from runtime state, and callback
+  decisions after the widget tree is loaded.
+- Do not use `root` in KV to refer to the PythonHere global `root`. In KV,
+  `root` means the current KV rule/root widget.
+- When a custom root class owns Kivy properties, define the class in Python
+  before `Builder.load_string(KV)` and end KV with a concrete instance of that
+  class.