feat(web): add branding controls and polish console UX

Author: ChesterRa

docs/standards/CCCC_DAEMON_IPC_V1.md

@@ -371,6 +371,41 @@ Result:
 { observability: Record<string, unknown> }
 ```
 
+#### `branding_get`
+
+Args: none
+
+Result:
+```ts
+{
+  branding: {
+    product_name: string
+    logo_icon_asset_path?: string
+    favicon_asset_path?: string
+    updated_at?: string
+  }
+}
+```
+
+#### `branding_update`
+
+Args:
+```ts
+{ by?: "user"; patch: Record<string, unknown> }
+```
+
+Result:
+```ts
+{
+  branding: {
+    product_name: string
+    logo_icon_asset_path?: string
+    favicon_asset_path?: string
+    updated_at?: string
+  }
+}
+```
+
 #### `debug_snapshot`
 
 Developer-mode diagnostic snapshot (global + optional group context).

src/cccc/daemon/ops/daemon_core_ops.py

@@ -21,6 +21,8 @@ def try_handle_daemon_core_op(
     get_observability: Callable[[], Dict[str, Any]],
     update_observability_settings: Callable[[Dict[str, Any]], Dict[str, Any]],
     apply_observability_settings: Callable[[Dict[str, Any]], None],
+    get_web_branding: Callable[[], Dict[str, Any]],
+    update_web_branding_settings: Callable[[Dict[str, Any]], Dict[str, Any]],
 ) -> Optional[Tuple[DaemonResponse, bool]]:
     if op == "ping":
         return (
@@ -60,4 +62,20 @@ def try_handle_daemon_core_op(
         except Exception as e:
             return _error("observability_update_failed", str(e)), False
 
+    if op == "branding_get":
+        return DaemonResponse(ok=True, result={"branding": get_web_branding()}), False
+
+    if op == "branding_update":
+        by = str(args.get("by") or "user").strip()
+        if by and by != "user":
+            return _error("permission_denied", "only user can update global branding settings"), False
+        patch = args.get("patch") if isinstance(args.get("patch"), dict) else {}
+        if not patch:
+            return DaemonResponse(ok=True, result={"branding": get_web_branding()}), False
+        try:
+            updated = update_web_branding_settings(dict(patch))
+            return DaemonResponse(ok=True, result={"branding": updated}), False
+        except Exception as e:
+            return _error("branding_update_failed", str(e)), False
+
     return None

src/cccc/daemon/request_dispatch_ops.py

@@ -46,6 +46,8 @@ class RequestDispatchDeps:
     get_observability: Callable[[], dict[str, Any]]
     update_observability_settings: Callable[..., bool]
     apply_observability_settings: Callable[[dict[str, Any]], bool]
+    get_web_branding: Callable[[], dict[str, Any]]
+    update_web_branding_settings: Callable[..., bool]
     developer_mode_enabled: Callable[[], bool]
     effective_runner_kind: Callable[[str], str]
     throttle_debug_summary: Callable[[], dict[str, Any]]
@@ -114,6 +116,8 @@ def dispatch_request(
         get_observability=deps.get_observability,
         update_observability_settings=deps.update_observability_settings,
         apply_observability_settings=deps.apply_observability_settings,
+        get_web_branding=deps.get_web_branding,
+        update_web_branding_settings=deps.update_web_branding_settings,
     )
     if daemon_core_resp is not None:
         return daemon_core_resp

src/cccc/daemon/server.py

@@ -19,7 +19,12 @@
 from ..kernel.actors import find_actor, find_foreman, update_actor, get_effective_role
 from ..kernel.blobs import resolve_blob_attachment_path
 from ..kernel.ledger_retention import compact as compact_ledger
-from ..kernel.settings import get_observability_settings, update_observability_settings
+from ..kernel.settings import (
+    get_observability_settings,
+    get_web_branding_settings,
+    update_observability_settings,
+    update_web_branding_settings,
+)
 from ..kernel.terminal_transcript import get_terminal_transcript_settings
 from ..kernel.messaging import disabled_recipient_actor_ids
 from ..paths import ensure_home
@@ -654,6 +659,8 @@ def _request_dispatch_deps() -> RequestDispatchDeps:
         get_observability=_get_observability,
         update_observability_settings=update_observability_settings,
         apply_observability_settings=lambda obs: _apply_observability_settings(ensure_home(), obs),
+        get_web_branding=get_web_branding_settings,
+        update_web_branding_settings=update_web_branding_settings,
         developer_mode_enabled=_developer_mode_enabled,
         effective_runner_kind=_effective_runner_kind,
         throttle_debug_summary=THROTTLE.debug_summary,

src/cccc/kernel/settings.py

@@ -158,6 +158,18 @@ def _copy_runtime_pool(pool: List[RuntimePoolEntry]) -> List[RuntimePoolEntry]:
 }
 
 
+# ---------------------------------------------------------------------------
+# Web branding (global)
+# ---------------------------------------------------------------------------
+
+DEFAULT_WEB_BRANDING: Dict[str, Any] = {
+    "product_name": "CCCC",
+    "logo_icon_asset_path": "",
+    "favicon_asset_path": "",
+    "updated_at": "",
+}
+
+
 def _as_bool(v: Any, default: bool) -> bool:
     if isinstance(v, bool):
         return v
@@ -252,6 +264,20 @@ def _merge_remote_access(raw: Any) -> Dict[str, Any]:
     return base
 
 
+def _merge_web_branding(raw: Any) -> Dict[str, Any]:
+    """Merge/validate web branding settings with defaults."""
+    base = dict(DEFAULT_WEB_BRANDING)
+    if not isinstance(raw, dict):
+        return base
+
+    product_name = str(raw.get("product_name") or "").strip()
+    base["product_name"] = product_name or str(DEFAULT_WEB_BRANDING["product_name"])
+    base["logo_icon_asset_path"] = str(raw.get("logo_icon_asset_path") or "").strip()
+    base["favicon_asset_path"] = str(raw.get("favicon_asset_path") or "").strip()
+    base["updated_at"] = _as_str(raw.get("updated_at"), str(base["updated_at"]))
+    return base
+
+
 def get_observability_settings() -> Dict[str, Any]:
     """Get merged observability settings (global)."""
     settings = load_settings()
@@ -311,6 +337,12 @@ def get_remote_access_settings() -> Dict[str, Any]:
     return _merge_remote_access(settings.get("remote_access"))
 
 
+def get_web_branding_settings() -> Dict[str, Any]:
+    """Get merged web branding settings (global)."""
+    settings = load_settings()
+    return _merge_web_branding(settings.get("web_branding"))
+
+
 def resolve_remote_access_web_binding() -> Dict[str, Any]:
     """Resolve effective Web binding with explicit settings/env/default precedence."""
     settings = load_settings()
@@ -420,6 +452,40 @@ def update_remote_access_settings(patch: Dict[str, Any]) -> Dict[str, Any]:
     return _merge_remote_access(raw)
 
 
+def update_web_branding_settings(patch: Dict[str, Any]) -> Dict[str, Any]:
+    """Update web branding settings in ~/.cccc/settings.yaml and return merged result."""
+    settings = load_settings()
+    current = _merge_web_branding(settings.get("web_branding"))
+    if not isinstance(patch, dict) or not patch:
+        return current
+
+    raw = dict(settings.get("web_branding") if isinstance(settings.get("web_branding"), dict) else {})
+    changed = False
+
+    if "product_name" in patch:
+        product_name = str(patch.get("product_name") or "").strip()
+        raw["product_name"] = product_name or str(DEFAULT_WEB_BRANDING["product_name"])
+        changed = True
+
+    if "logo_icon_asset_path" in patch:
+        raw["logo_icon_asset_path"] = str(patch.get("logo_icon_asset_path") or "").strip()
+        changed = True
+
+    if "favicon_asset_path" in patch:
+        raw["favicon_asset_path"] = str(patch.get("favicon_asset_path") or "").strip()
+        changed = True
+
+    if "updated_at" in patch:
+        raw["updated_at"] = _as_str(patch.get("updated_at"), str(raw.get("updated_at") or ""))
+        changed = True
+    elif changed:
+        raw["updated_at"] = utc_now_iso()
+
+    settings["web_branding"] = raw
+    save_settings(settings)
+    return _merge_web_branding(raw)
+
+
 def _settings_path() -> Path:
     return ensure_home() / "settings.yaml"
 

src/cccc/ports/web/app.py

@@ -96,7 +96,7 @@ def _web_mode() -> Literal["normal", "exhibit"]:
     return "normal"
 
 
-_PUBLIC_API_PATHS = frozenset({"/api/v1/health"})
+_PUBLIC_API_PATHS = frozenset({"/api/v1/health", "/api/v1/branding"})
 
 
 def _is_public_ui_path(request: Request) -> bool:
@@ -107,7 +107,7 @@ def _is_public_ui_path(request: Request) -> bool:
 def _is_public_path(request: Request) -> bool:
     """Routes that bypass token authentication (UI assets + health check)."""
     path = str(request.url.path or "")
-    return _is_public_ui_path(request) or path in _PUBLIC_API_PATHS
+    return _is_public_ui_path(request) or path in _PUBLIC_API_PATHS or path.startswith("/api/v1/branding/assets/")
 
 
 def _request_token_parts(request: Request) -> tuple[str, Literal["", "header", "cookie", "query"]]:

src/cccc/ports/web/branding.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+from pathlib import Path
+from typing import Any, Dict, Literal
+
+from ...paths import ensure_home
+from ...util.fs import atomic_write_bytes
+
+BrandingAssetKind = Literal["logo_icon", "favicon"]
+
+_BRANDING_MAX_BYTES = 2 * 1024 * 1024
+_DEFAULT_PRODUCT_NAME = "CCCC"
+_DEFAULT_LOGO_ICON_URL = "/ui/logo.svg"
+_DEFAULT_FAVICON_URL = "/ui/logo.svg"
+
+_ALLOWED_MIME_TYPES: dict[str, set[str]] = {
+    "logo_icon": {
+        "image/svg+xml",
+        "image/png",
+        "image/jpeg",
+        "image/webp",
+        "image/gif",
+        "image/avif",
+        "image/x-icon",
+        "image/vnd.microsoft.icon",
+    },
+    "favicon": {
+        "image/svg+xml",
+        "image/png",
+        "image/x-icon",
+        "image/vnd.microsoft.icon",
+    },
+}
+
+_EXTENSION_BY_MIME: dict[str, str] = {
+    "image/svg+xml": ".svg",
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "image/avif": ".avif",
+    "image/x-icon": ".ico",
+    "image/vnd.microsoft.icon": ".ico",
+}
+
+
+def normalize_branding_asset_kind(value: str) -> BrandingAssetKind:
+    normalized = str(value or "").strip().lower()
+    if normalized in {"logo_icon", "favicon"}:
+        return normalized  # type: ignore[return-value]
+    raise ValueError("asset kind must be one of: logo_icon, favicon")
+
+
+def branding_asset_dir() -> Path:
+    return ensure_home() / "state" / "web_branding"
+
+
+def _branding_asset_rel_path(filename: str) -> str:
+    return str(Path("state") / "web_branding" / filename).replace("\\", "/")
+
+
+def resolve_branding_asset_path(rel_path: str) -> Path:
+    normalized = str(rel_path or "").strip().replace("\\", "/")
+    if not normalized:
+        raise FileNotFoundError("branding asset path is empty")
+    base = ensure_home().resolve()
+    target = (base / Path(*Path(normalized).parts)).resolve()
+    try:
+        target.relative_to(base)
+    except ValueError as exc:
+        raise FileNotFoundError("branding asset path is outside CCCC_HOME") from exc
+    return target
+
+
+def store_branding_asset(*, asset_kind: BrandingAssetKind, data: bytes, content_type: str, filename: str = "") -> Dict[str, Any]:
+    mime_type = str(content_type or "").strip().lower()
+    if not mime_type:
+        guessed, _ = mimetypes.guess_type(str(filename or "").strip())
+        mime_type = str(guessed or "").strip().lower()
+    if mime_type not in _ALLOWED_MIME_TYPES[asset_kind]:
+        raise ValueError(f"unsupported {asset_kind} type: {mime_type or 'unknown'}")
+    if len(data) > _BRANDING_MAX_BYTES:
+        raise ValueError(f"{asset_kind} file too large")
+
+    digest = hashlib.sha256(data).hexdigest()
+    ext = _EXTENSION_BY_MIME.get(mime_type) or Path(str(filename or "").strip()).suffix.lower() or ".bin"
+    stored_name = f"{asset_kind}_{digest[:16]}{ext}"
+    abs_path = branding_asset_dir() / stored_name
+    atomic_write_bytes(abs_path, data)
+    return {
+        "asset_kind": asset_kind,
+        "mime_type": mime_type,
+        "bytes": len(data),
+        "sha256": digest,
+        "rel_path": _branding_asset_rel_path(stored_name),
+        "public_url": f"/api/v1/branding/assets/{asset_kind}?v={digest[:16]}",
+    }
+
+
+def delete_branding_asset(rel_path: str) -> None:
+    try:
+        target = resolve_branding_asset_path(rel_path)
+        if target.exists():
+            target.unlink()
+    except Exception:
+        pass
+
+
+def build_branding_payload(raw: Dict[str, Any]) -> Dict[str, Any]:
+    product_name = str(raw.get("product_name") or "").strip() or _DEFAULT_PRODUCT_NAME
+    logo_rel_path = str(raw.get("logo_icon_asset_path") or "").strip()
+    favicon_rel_path = str(raw.get("favicon_asset_path") or "").strip()
+    updated_at = str(raw.get("updated_at") or "").strip() or None
+
+    logo_url = (
+        f"/api/v1/branding/assets/logo_icon?v={updated_at or 'default'}"
+        if logo_rel_path
+        else _DEFAULT_LOGO_ICON_URL
+    )
+    favicon_url = (
+        f"/api/v1/branding/assets/favicon?v={updated_at or 'default'}"
+        if favicon_rel_path
+        else (logo_url if logo_rel_path else _DEFAULT_FAVICON_URL)
+    )
+    return {
+        "product_name": product_name,
+        "logo_icon_url": logo_url,
+        "favicon_url": favicon_url,
+        "has_custom_logo_icon": bool(logo_rel_path),
+        "has_custom_favicon": bool(favicon_rel_path),
+        "updated_at": updated_at,
+    }