gpt-5.3-codex review phase 2 - update instructions & skills

.github/instructions/ui.instructions.md

@@ -11,6 +11,9 @@ Keep dependencies flowing in this direction:
 
 Pages may depend on application services and framework-provided dependencies. Components may depend on smaller components and shared presentation helpers. Services and domain modules must never depend on the UI.
 
+Cross-cutting error behavior must follow
+[error-handling instructions](./error-handling.instructions.md).
+
 ## Package Root
 
 - Keep `ui/__init__.py` as the UI composition root: register global assets, register pages, and mount NiceGUI on FastAPI.
@@ -44,17 +47,31 @@ Pages may depend on application services and framework-provided dependencies. Co
 - Keep all application CSS in `ui/static/theme.css`; do not add page- or component-specific stylesheets or embed style blocks in Python components.
 - Load `theme.css` once from the composition root with `ui.add_css(..., shared=True)`.
 - Read stylesheet text through `importlib.resources.files(...)` so loading works from installed packages and is independent of the working directory.
-- Centralize CSS reading in one typed helper cached by resource path with `functools.cache` or an equivalent unbounded `lru_cache`. Cache the immutable stylesheet text to avoid repeated resource I/O; keep NiceGUI registration at the composition root.
+- Centralize CSS reading in one typed helper cached by resource path.
 - Do not encode application behavior in CSS or other static assets.
 
 ## State and Side Effects
 
 - Limit component state to ephemeral interaction state such as loading flags, form values, dialogs, and expansion state.
-- Application and worker state must be resolved at the page or application boundary and passed through narrow interfaces such as callbacks or notifier protocols.
-- Keep filesystem, network, provider, and worker orchestration behind application services or dedicated adapters. UI code may trigger those operations but must not implement them.
+- Application and worker state must be resolved at the page or application boundary and passed through narrow interfaces.
+- Keep filesystem, network, provider, and worker orchestration behind application services or dedicated adapters.
+
+## Media Route Safety Rules
+
+Two patterns are approved:
+
+1. **Record-validated API routes** for print/export contexts.
+2. **Controlled upload URL resolver** (`components/media_urls.py`) for general UI media.
+
+Prohibited patterns:
+
+- Direct `file://` links or exposing local filesystem paths.
+- Manual URL construction from raw `Path` values in pages/components.
+- User-facing payloads containing local absolute paths.
 
 ## V4 Contract Alignment
 
 - Treat `docs/ver4/` as the active baseline and `docs/ver4/history.md` as historical reference only.
 - Use status vocabulary exactly as modeled (`queued`, `processing`, `transcribed`, `partial_success`, `failed`; and `pending`, `transcribed`, `failed`, `cancelled`).
-- Print/export media flows must use record-validated routes from API modules; direct local filesystem paths are prohibited.
+- Print/export media flows must use record-validated routes; direct local filesystem paths are prohibited.
+- If lifecycle wording/behavior changes, update corresponding `docs/ui/pages/*.md` contracts in the same change.