@openhands/extensions 0.28.0 → 0.30.0

package/plugins/vulnerability-remediation/skills/github/scripts/agent_conversation.py

@@ -3,7 +3,9 @@
 import json
 import os
 import time
+from collections.abc import Callable
 from urllib.error import HTTPError
+from urllib.parse import urlencode
 from urllib.request import Request, urlopen
 from uuid import NAMESPACE_URL, UUID, uuid4, uuid5
 
@@ -113,6 +115,10 @@ class CloudConversations:
             },
         )
 
+    def agent_profiles(self) -> list[dict]:
+        listing = self._request("GET", "/api/agent-profiles")
+        return (listing or {}).get("profiles") or []
+
     def run(self, conversation: dict) -> None:
         """Start the next turn of an idle conversation on its own Agent Server."""
         try:
@@ -152,6 +158,17 @@ def _user_message(text: str) -> dict:
     return {"role": "user", "content": [{"type": "text", "text": text}]}
 
 
+def _render(prompt, conversation_id) -> str:
+    """The text of `prompt` for the conversation it is delivered to.
+
+    A caller that must name the receiving conversation in its own prompt (a
+    marker the deterministic side later looks for, say) passes a function of
+    the conversation id, because only delivery decides which conversation that
+    is.
+    """
+    return prompt(str(conversation_id)) if callable(prompt) else prompt
+
+
 class AgentConversationDispatcher:
     """Deliver one revision at a time to a stable conversation for each subject."""
 
@@ -189,7 +206,11 @@ class AgentConversationDispatcher:
         return self._workspace.__exit__(*args)
 
     def deliver(
-        self, subject: str, delivery: str, prompt: str, head: str = ""
+        self,
+        subject: str,
+        delivery: str,
+        prompt: str | Callable[[str], str],
+        head: str = "",
     ) -> dict[str, str]:
         """Deliver one revision of `subject`, deduping a repeated head.
 
@@ -202,6 +223,7 @@ class AgentConversationDispatcher:
         A conversation already running for this head is reported `in_progress`
         and left alone, whatever the new delivery says. Callers with no revision
         identity leave `head` empty and keep the delivery-key-only behavior.
+        `prompt` may be a function of the receiving conversation's id.
         """
         conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
         state_key = f"{_CONVERSATION_KEY_PREFIX}{conversation_id}"
@@ -252,6 +274,67 @@ class AgentConversationDispatcher:
             "conversation_id": str(conversation_id),
         }
 
+    def subject_conversation(self, subject: str) -> str | None:
+        """The conversation this automation currently delivers `subject` to."""
+        conversation_id = uuid5(NAMESPACE_URL, f"{self.automation_id}:{subject}")
+        record = _kv_request(f"{_CONVERSATION_KEY_PREFIX}{conversation_id}", "GET")
+        return (record or {}).get("conversation_id") or None
+
+    def llm_provenance(self, conversation_id: str) -> tuple[str, str] | None:
+        """The LLM profile name and model a conversation runs, or None if it is gone.
+
+        Both are read back from the conversation, never from the automation's
+        current settings: the server resolves the agent profile when it starts
+        the conversation, and a reused conversation keeps that LLM after the
+        profile is edited. The model is the conversation's own. The LLM profile
+        name comes from the launching agent profile only while that profile is
+        still at its launch revision, and is `unknown` otherwise.
+        """
+        if self._cloud:
+            conversation = self._cloud.get(conversation_id)
+            if conversation is None:
+                return None
+            model = conversation.get("llm_model")
+        else:
+            try:
+                conversation = self._agent_server_get(
+                    f"/api/conversations/{conversation_id}"
+                )
+            except HTTPError as exc:
+                if exc.code == 404:
+                    return None
+                raise
+            agent = conversation.get("agent") or {}
+            model = conversation.get("current_model_id")
+            if model is None and agent.get("kind") != "ACPAgent":
+                model = (agent.get("llm") or {}).get("model")
+        launched = conversation.get("launched_agent_profile") or {}
+        profile = "unknown"
+        if launched.get("agent_profile_id"):
+            try:
+                if self._cloud:
+                    profiles = self._cloud.agent_profiles()
+                else:
+                    listing = self._agent_server_get("/api/agent-profiles")
+                    profiles = (listing or {}).get("profiles") or []
+            except Exception as exc:  # noqa: BLE001 - the model is still known
+                print(f"Could not read agent profiles: {type(exc).__name__}: {exc}")
+                profiles = []
+            for item in profiles:
+                if str(item.get("id")) == str(launched["agent_profile_id"]):
+                    if item.get("revision") == launched.get("revision"):
+                        profile = item.get("llm_profile_ref") or "unknown"
+                    break
+        return profile, model or "unknown"
+
+    def _agent_server_get(self, path: str) -> dict:
+        request = Request(
+            f"{self.agent_url.rstrip('/')}{path}",
+            headers={"X-Session-API-Key": self.api_key},
+        )
+        with urlopen(request, timeout=90) as response:
+            return json.load(response)
+
     def _deliver_cloud(
         self,
         record,
@@ -287,7 +370,9 @@ class AgentConversationDispatcher:
 
         if conversation is None:
             new_id = uuid4() if record else conversation_id
-            self._cloud.start(new_id, self.profile_id, subject, prompt)
+            self._cloud.start(
+                new_id, self.profile_id, subject, _render(prompt, new_id)
+            )
             return "created", new_id
 
         status = conversation.get("execution_status")
@@ -303,10 +388,10 @@ class AgentConversationDispatcher:
                 # The API reports an execution status only while the sandbox
                 # runs, so an errored conversation whose sandbox was already
                 # paused is not seen here and keeps reporting deduplicated.
-                self._cloud.send(conversation, prompt)
+                self._cloud.send(conversation, _render(prompt, current_id))
                 return "retried", current_id
             return "deduplicated", current_id
-        self._cloud.send(conversation, prompt)
+        self._cloud.send(conversation, _render(prompt, current_id))
         return "resumed", current_id
 
     def _deliver_local(
@@ -326,12 +411,13 @@ class AgentConversationDispatcher:
             conversation = RemoteConversation.create(
                 self._workspace,
                 StartConversationRequest(
-                    workspace=LocalWorkspace(working_dir="/workspace"),
+                    workspace=LocalWorkspace(working_dir=self._workspace.working_dir),
                     conversation_id=conversation_id,
                     agent_profile_id=self.profile_id,
                     secrets=self._secrets,
                     initial_message=SendMessageRequest(
-                        content=[TextContent(text=prompt)], run=True
+                        content=[TextContent(text=_render(prompt, conversation_id))],
+                        run=True,
                     ),
                 ),
                 visualizer=None,
@@ -365,7 +451,7 @@ class AgentConversationDispatcher:
                         # the work finished, so send the revision again rather
                         # than strand it.
                         conversation.update_secrets(self._secrets)
-                        conversation.send_message(prompt)
+                        conversation.send_message(_render(prompt, conversation_id))
                         conversation.run(blocking=False)
                         disposition = "retried"
                     else:
@@ -375,8 +461,138 @@ class AgentConversationDispatcher:
                     # work on the same subject: reuse the conversation and send
                     # the revision as its next turn.
                     conversation.update_secrets(self._secrets)
-                    conversation.send_message(prompt)
+                    conversation.send_message(_render(prompt, conversation_id))
                     conversation.run(blocking=False)
         finally:
             conversation.close()
         return disposition
+
+    def review_snapshot(self, conversation_id):
+        if self._cloud:
+            conversation = self._cloud.get(conversation_id)
+            if conversation is None:
+                return "missing", ""
+            status = conversation.get("execution_status", "unknown")
+            if status != "finished":
+                return status, ""
+            result = self._cloud._request(
+                "GET",
+                f"{conversation['conversation_url']}/agent_final_response",
+                headers={"X-Session-API-Key": conversation["session_api_key"]},
+            )
+            return status, result.get("response", "")
+        headers = {"X-Session-API-Key": self.api_key}
+        base = f"{self.agent_url.rstrip('/')}/api/conversations/{conversation_id}"
+        try:
+            with urlopen(Request(base, headers=headers), timeout=90) as response:
+                status = json.load(response).get("execution_status", "unknown")
+        except HTTPError as exc:
+            if exc.code == 404:
+                return "missing", ""
+            raise
+        if status != "finished":
+            return status, ""
+        with urlopen(
+            Request(base + "/agent_final_response", headers=headers), timeout=90
+        ) as response:
+            return status, json.load(response).get("response", "")
+
+    def start_review_work(self, conversation_id, subject, prompt):
+        if self._cloud:
+            self._cloud.start(UUID(conversation_id), self.profile_id, subject, prompt)
+            return
+        if self._workspace is None:
+            raise RuntimeError("Dispatcher must be used as a context")
+        conversation = RemoteConversation.create(
+            self._workspace,
+            StartConversationRequest(
+                workspace=LocalWorkspace(working_dir=self._workspace.working_dir),
+                conversation_id=UUID(conversation_id),
+                agent_profile_id=self.profile_id,
+                secrets=self._secrets,
+                initial_message=SendMessageRequest(
+                    content=[TextContent(text=prompt)], run=True
+                ),
+            ),
+            visualizer=None,
+        )
+        conversation.close()
+
+
+class ReviewCoordination:
+    """CAS against the automation service's shared, user-authorized KV namespace."""
+
+    def __init__(self):
+        namespace = os.environ.get("REVIEW_COORDINATION_AUTOMATION_ID")
+        key = os.environ.get("REVIEW_COORDINATION_API_KEY")
+        if not namespace or not key:
+            raise RuntimeError(
+                "Structured reviews require shared coordination namespace and API key"
+            )
+        self.query = urlencode({"automation_id": str(UUID(namespace))})
+        self.base = os.environ["AUTOMATION_API_URL"].rstrip("/")
+        self.headers = {"X-Session-API-Key": key, "Content-Type": "application/json"}
+
+    def request(self, key, method="GET", value=None, condition=""):
+        request = Request(
+            f"{self.base}/v1/kv/{key}?{self.query}&{condition}",
+            data=None if value is None else json.dumps(value).encode(),
+            headers=self.headers,
+            method=method,
+        )
+        try:
+            with urlopen(request, timeout=90) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            if method == "GET" and exc.code == 404:
+                return None
+            raise
+
+    def claim(self, subject, *, existing_only=False):
+        key = "review-work-" + str(uuid5(NAMESPACE_URL, subject))
+        for _ in range(5):
+            current = self.request(key, condition="meta=true")
+            if current is None and existing_only:
+                return None
+            value = (current or {}).get("value") or {}
+            if value.get("lease_until", 0) > time.time():
+                return None
+            value = {**value, "owner": str(uuid4()), "lease_until": time.time() + 180}
+            condition = f"if_version={current['version']}" if current else "nx=true"
+            try:
+                self.request(key, "PUT", value, condition)
+                return ReviewLease(self, key, value)
+            except HTTPError as exc:
+                if exc.code != 409:
+                    raise
+        return None
+
+
+class ReviewLease:
+    def __init__(self, store, key, value):
+        self.store, self.key, self.value = store, key, value
+        self.owner = value["owner"]
+
+    def save(self, **changes):
+        for _ in range(5):
+            current = self.store.request(self.key, condition="meta=true")
+            value = current["value"]
+            if (
+                value.get("owner") != self.owner
+                or value.get("lease_until", 0) <= time.time()
+            ):
+                raise RuntimeError("Review lease lost; refusing side effects")
+            updated = {**self.value, **changes}
+            try:
+                self.store.request(
+                    self.key, "PUT", updated, f"if_version={current['version']}"
+                )
+                self.value = updated
+                return
+            except HTTPError as exc:
+                if exc.code != 409:
+                    raise
+        raise RuntimeError("Review coordination contention; retry next scan")
+
+    def release(self):
+        self.save(lease_until=0)

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.28.0"
+version = "0.30.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.28.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.30.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/skills/canvas-extension-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canvas-extension-api
-description: This skill should be used when the user asks to "create an OpenHands App", "scaffold a Canvas App", "build an app with the Canvas Extensions API", "build an Agent Canvas App", "bundle a single-file Canvas App", "build a Sidecar-backed Canvas App", "add onboarding for an App service", "add a custom interface to Agent Canvas", "validate an OpenHands App", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.
+description: This skill should be used when the user asks to "create an OpenHands App", "scaffold a Canvas App", "build an app with the Canvas Extensions API", "build an Agent Canvas App", "bundle a single-file Canvas App", "build a Sidecar-backed Canvas App", "add onboarding for an App service", "add a custom interface to Agent Canvas", "validate an OpenHands App", "make a Canvas App look native", "match Agent Canvas styles", "style a canvas extension", "reuse OpenHands design tokens", "add native Tailwind classes to an app", or mentions Canvas Apps, Agent Canvas extensions, Blob-importable app bundles, registerPage, app pages, Sidecars, or canvas extension packages.
 ---
 
 # Canvas Extensions API
@@ -195,6 +195,8 @@ Assume activation, mounting, and disposal may happen repeatedly during hot enabl
 
 Render within the supplied `container`; do not replace unrelated Canvas DOM. Scope CSS under an app-specific root class. Prefer Canvas CSS variables with sensible fallbacks rather than copying host implementation classes.
 
+Read `references/native-design.md` before styling an App page. It covers the core rule (reuse tokens, not host internals), the three implementation paths (dependency-free, Tailwind-bundled, existing CSS), the Tailwind v4 theme mapping to host variables, layout and density conventions, copy-ready component recipes, the raw scoped CSS alternative, and a mount-safe style helper. Treat it as the authoritative design reference for Apps.
+
 Provide:
 
 - semantic structure and headings inside the supplied container. Canvas already owns the outer `<main aria-label={page title}>`, so do not add a nested `main` or duplicate page landmark label;
@@ -281,5 +283,6 @@ Summarize:
 - `references/testing-and-installation.md` - test strategy, manual Canvas workflow, and installation coordinates.
 - `references/packaging-recipes.md` - one-file Vite, CSS, assets, Workers, and WASM rules.
 - `references/backend-safety.md` - authenticated requests, command safety, persistence, and prerequisite onboarding.
+- `references/native-design.md` - native Agent Canvas styling: token reuse, Tailwind mapping, layout, component recipes, scoped CSS, and style injection.
 - `references/acceptance-checklist.md` - automated checks and the local install/enable/reload lifecycle.
 - `scripts/validate-extension.mjs` - dependency-free static artifact validator for an App package directory.

package/skills/canvas-extension-api/references/backend-safety.md

@@ -10,14 +10,14 @@ For a CLI, binary, compiler, database, or Sidecar, read [sidecar-pattern.md](sid
 
 ## Package-owned managed backends
 
-The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` through `GET /server_info`; never infer support from an endpoint failure, Canvas internals, or a guessed port. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
+The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Remote artifact sources additionally require [software-agent-sdk PR #5503](https://github.com/OpenHands/software-agent-sdk/pull/5503). Until releases containing the needed changes land, those revisions or PR heads are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` through `GET /server_info`; never infer support from an endpoint failure, Canvas internals, or a guessed port. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
 
 A managed backend is declarative, not an install hook. Installation, enablement, activation, and ordinary page mounts never prepare or start it. Show the resolved revision and backend declaration, then require explicit user consent before calling prepare and start with that exact revision. Updating or replacing the package invalidates approval. Never put a credential in the manifest, argv, browser bundle, URL, or log.
 
 For embedded backend views, require the configured ingress to be a separate browser origin from Canvas. That origin is the isolation boundary. Apply the server-returned sandbox exactly, including `allow-same-origin`; removing it breaks Origin validation, partitioned-cookie delivery, and Worker creation in Chromium. Do not replace origin isolation with an opaque sandbox origin.
 
-The Agent Server selects the current platform artifact, verifies its lowercase SHA-256 checksum, extracts it safely to immutable content-addressed storage, and runs only the declared structured argv without a shell. The executable must remain inside `{artifact_dir}`. Supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. Inherited environment names are restricted to the server's non-credential allowlist; ambient Agent Server credentials do not flow to the child.
+The Agent Server selects the current platform artifact, verifies its lowercase SHA-256 checksum, extracts it safely to immutable content-addressed storage, and runs only the declared structured argv without a shell. An artifact may use either a contained package-relative `path` or a credential-free HTTPS `url`, never both. Remote downloads enforce redirect, size, scheme, checksum, and archive-entry constraints; `strip_components` is bounded from 0 through 16. The executable must remain inside `{artifact_dir}`. Supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. The child receives an App-owned `HOME` below `{data_dir}`. Inherited environment names are restricted to the server's non-credential allowlist; ambient Agent Server credentials do not flow to the child.
 
-Only local Linux amd64 and arm64 artifacts are supported initially. Treat `unsupported` as an explicit UI state. The owned process is constrained by its launch contract and process group but is not OS-isolated; run untrusted backend code only inside a suitably isolated Agent Server runtime.
+Only local Agent Server hosts on Linux amd64 and arm64 are supported initially. Treat `unsupported` as an explicit UI state. The owned process is constrained by its launch contract and process group but is not OS-isolated; run untrusted backend code only inside a suitably isolated Agent Server runtime.
 
 Backend data belongs to the service independently of the installed bundle. Disable and uninstall stop the owned process and revoke browser sessions but preserve mutable data. Data deletion is a separate explicit action. Installed Apps and their backends belong to one Agent Server; do not assume a service or its data is shared across isolated conversation runtimes.

package/skills/canvas-extension-api/references/native-design.md

@@ -0,0 +1,250 @@
+# Native OpenHands App design
+
+Build Apps for Agent Canvas that visually belong in the host while remaining a self-contained, safe extension package. Use this reference together with the main `SKILL.md` workflow before changing an App's UI.
+
+## Core rule: reuse tokens, not host internals
+
+Treat an App bundle as an independent frontend. Do not import Agent Canvas React components, utility modules, CSS files, font files, Tailwind configuration, aliases, or private DOM classes. The host imports the App as a self-contained Blob ESM module, so those imports will fail or create fragile coupling.
+
+Reuse the host's stable CSS custom properties instead. Scope every selector under a unique App root class and provide literal fallbacks so the page stays legible outside a current Canvas build. Tailwind utility names such as `bg-base` or `text-contrast` are **not globally available** to an App: they work only after the App's own Tailwind build maps them to the host variables.
+
+Use semantic names (`surface`, `foreground`, `border`, `primary`) rather than copying cool-grey hex values.
+
+## Choose the implementation path
+
+Choose the smallest path that matches the App package:
+
+| App implementation | Recommended styling approach |
+| --- | --- |
+| Dependency-free JavaScript | Inject one scoped CSS string from the entrypoint. Use host custom properties directly. |
+| React/TypeScript with Tailwind | Add an App-local Tailwind theme mapping to the host variables, then compile every class into the single `extension.js` artifact. |
+| Existing CSS module or CSS-in-JS setup | Define the semantic colors and component recipes in the App's own scoped stylesheet. |
+
+Never expect the host Tailwind compiler to scan or compile App source. Never use a CDN Tailwind runtime. Never attach App styles to `:root`, `html`, `body`, or global element selectors.
+
+## Tailwind setup for a bundled App
+
+For Tailwind v4, place an App-local mapping in the App stylesheet. This lets the App use Canvas-like classes while preserving portability:
+
+```css
+@import "tailwindcss";
+
+@theme inline {
+  --color-base: var(--oh-color-base);
+  --color-base-secondary: var(--oh-color-base-secondary);
+  --color-surface: var(--oh-surface);
+  --color-surface-raised: var(--oh-surface-raised);
+  --color-foreground: var(--oh-foreground);
+  --color-contrast: var(--oh-contrast);
+  --color-muted: var(--oh-muted);
+  --color-tertiary-alt: var(--oh-text-dim);
+  --color-border: var(--oh-border);
+  --color-border-subtle: var(--oh-border-subtle);
+  --color-focus: var(--oh-focus);
+  --color-interactive-hover: var(--oh-interactive-hover);
+  --color-primary: var(--oh-color-primary);
+  --color-on-primary: var(--oh-accent-foreground);
+  --color-danger: var(--oh-danger);
+}
+```
+
+Compile this stylesheet into `extension.js`; do not leave a linked CSS asset. For an App without Tailwind, use the matching raw CSS below instead. Use utility recipes only after adding this mapping.
+
+## Layout and density
+
+Let Canvas own the outer page and scrolling region. Do not add a second page shell, `h-screen`, global background, sidebar, or top navigation. Start with `min-h-full`, use `p-4 sm:p-6 lg:p-8`, and constrain dense content with `mx-auto w-full max-w-5xl`. Use `gap-4` for related controls, `gap-6` within sections, and `gap-8` between major sections. Use `rounded-lg` for controls and `rounded-xl` for cards and messages.
+
+Avoid gradients, glass effects, oversize headings, floating shadows, dense borders, and hard-coded dark greys. The native visual language is restrained: dark layered surfaces, cool-grey borders, warm primary actions, direct typography, and short transitions.
+
+## Interaction and state checklist
+
+- Apply `text-contrast` to headings and key labels; use `text-muted` or `text-tertiary-alt` for supporting copy.
+- Use the primary recipe for one dominant action. Use a bordered secondary action for alternatives. Do not make every button primary.
+- Use a 36px (`h-9`) control height and `rounded-lg` for input, select, and standard button controls.
+- Use `focus-visible` rather than removing outlines. Preserve disabled affordance with `disabled:cursor-not-allowed disabled:opacity-60`.
+- Animate only background, border, box-shadow, opacity, or transforms and include `motion-reduce:transition-none`.
+- Scope icon sizing and color within the App. Do not assume HeroUI, Lucide, or host icon packages exist.
+- Use `textContent`, framework escaping, or safe DOM creation for data from requests. Never inject response text with `innerHTML`.
+
+## Semantic token map
+
+| Intent | Host variable | Fallback |
+| --- | --- | --- |
+| Deep page base | `--oh-color-base` | `#0B0E14` |
+| Standard panel | `--oh-color-base-secondary` | `#21252F` |
+| Raised surface | `--oh-surface-raised` | `#2C313F` |
+| Main text | `--oh-contrast` | `#FFFFFF` |
+| Standard text | `--oh-foreground` | `#EEF2F7` |
+| Secondary text | `--oh-muted` | `#A3B0C4` |
+| Muted placeholder text | `--oh-text-dim` | `#7E8A9E` |
+| Standard border | `--oh-border` | `#4B5468` |
+| Subtle divider | `--oh-border-subtle` | `#383F50` |
+| Focus ring | `--oh-focus` | `#FFFFFF` |
+| Primary surface | `--oh-color-primary` | `#C9B974` |
+| Primary text | `--oh-accent-foreground` | `#0B0E14` |
+| Danger | `--oh-danger` | `#E76A5E` |
+| Success | `--oh-success` | `#A5E75E` |
+
+## Copy-ready Tailwind recipes
+
+Use these recipes only after mapping the semantic colors in the App-local Tailwind configuration above.
+
+### Content shell
+
+```tsx
+<div className="min-h-full p-4 sm:p-6 lg:p-8 text-foreground">
+  <div className="mx-auto flex w-full max-w-5xl flex-col gap-8">...</div>
+</div>
+```
+
+Do not use `h-screen`, `min-h-screen`, a host-like global background, or a nested `<main>`; Canvas supplies the page landmark and scroll context.
+
+### Page heading
+
+```tsx
+<header className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+  <div className="min-w-0">
+    <h1 className="text-xl font-semibold tracking-tight text-contrast">Page title</h1>
+    <p className="mt-1 text-sm text-muted">Short supporting description.</p>
+  </div>
+</header>
+```
+
+### Card or section
+
+```tsx
+<section className="rounded-xl border border-border bg-base-secondary p-4 sm:p-6">
+  <h2 className="text-base font-medium text-contrast">Section title</h2>
+  <p className="mt-1 text-sm text-muted">Explain the section briefly.</p>
+  <div className="mt-5 flex flex-col gap-4">...</div>
+</section>
+```
+
+Use `border-border-subtle` for dividers inside an existing card. Avoid default card shadows.
+
+### Controls and buttons
+
+```tsx
+const control =
+  "h-9 min-h-9 rounded-lg transition-[background-color,border-color,box-shadow,opacity] duration-75 motion-reduce:transition-none";
+
+const field = `${control} w-full min-w-0 border border-border bg-base-secondary px-3 text-sm text-contrast placeholder:text-tertiary-alt focus:border-contrast/40 focus:ring-1 focus:ring-contrast/20 focus:outline-none disabled:cursor-not-allowed disabled:opacity-60`;
+
+const primaryButton = `${control} inline-flex w-fit items-center justify-center gap-2 bg-primary px-3 text-sm font-normal text-on-primary hover:opacity-80 disabled:cursor-not-allowed disabled:opacity-30`;
+
+const secondaryButton = `${control} inline-flex w-fit items-center justify-center gap-2 border border-border bg-base-secondary px-3 text-sm font-normal text-contrast hover:bg-surface-raised disabled:cursor-not-allowed disabled:opacity-30`;
+```
+
+Use `label` plus `htmlFor`, keep field hints in `text-xs text-muted`, and express validation with `aria-invalid`, a `border-red-500`, and a linked `role="alert"` message using `text-xs text-red-400`.
+
+### Toolbar and responsive grid
+
+```tsx
+<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+  <div className="min-w-0">...</div>
+  <div className="flex flex-wrap items-center gap-2">...</div>
+</div>
+
+<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">...</div>
+```
+
+### Informational, error, and empty state
+
+```tsx
+<div className="rounded-xl border border-border bg-base-secondary p-6 text-center">
+  <h2 className="text-base font-medium text-contrast">Nothing here yet</h2>
+  <p className="mt-2 text-sm text-muted">Describe the next useful action.</p>
+  <button className={`${primaryButton} mt-4`}>Create item</button>
+</div>
+
+<div role="alert" className="rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3 text-sm text-red-200">
+  The request could not be completed.
+</div>
+```
+
+Use `animate-pulse` with `motion-reduce:animate-none` only for short loading placeholders; reserve space with shapes matching loaded cards or rows.
+
+### Compact tabs
+
+```tsx
+<div role="tablist" aria-label="View options" className="flex w-fit gap-1 rounded-lg border border-border bg-base-secondary p-1">
+  <button role="tab" aria-selected="true" className="rounded-md bg-interactive-hover px-3 py-1.5 text-sm text-contrast">Overview</button>
+  <button role="tab" aria-selected="false" className="rounded-md px-3 py-1.5 text-sm text-muted hover:bg-surface-raised hover:text-contrast">Activity</button>
+</div>
+```
+
+Implement keyboard tab behavior when tabs change content; use regular buttons for simple filters.
+
+## Raw scoped CSS alternative
+
+Use this approach for dependency-free Apps. Apply it only after inserting an App root such as `.acme-dashboard`.
+
+```css
+.acme-dashboard {
+  color: var(--oh-foreground, #EEF2F7);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.acme-dashboard .card {
+  border: 1px solid var(--oh-border, #4B5468);
+  border-radius: 12px;
+  background: var(--oh-color-base-secondary, #21252F);
+  padding: 1.5rem;
+}
+.acme-dashboard .field,
+.acme-dashboard .button {
+  min-height: 2.25rem;
+  border-radius: 8px;
+  transition: background-color 75ms, border-color 75ms, box-shadow 75ms, opacity 75ms;
+}
+.acme-dashboard .field {
+  width: 100%; border: 1px solid var(--oh-border, #4B5468);
+  background: var(--oh-color-base-secondary, #21252F);
+  color: var(--oh-contrast, #FFF); padding: 0 0.75rem;
+}
+.acme-dashboard .field:focus-visible,
+.acme-dashboard .button:focus-visible {
+  outline: none; border-color: color-mix(in srgb, var(--oh-contrast, #FFF) 40%, transparent);
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--oh-contrast, #FFF) 20%, transparent);
+}
+.acme-dashboard .button--primary {
+  border: 0; background: var(--oh-color-primary, #C9B974);
+  color: var(--oh-accent-foreground, #0B0E14); padding: 0 0.75rem;
+}
+@media (prefers-reduced-motion: reduce) {
+  .acme-dashboard .field, .acme-dashboard .button { transition: none; }
+}
+```
+
+## Mount-safe injected style helper
+
+Use one marker per mounted App root and remove the node during cleanup.
+
+```js
+function installStyles(css, marker) {
+  const style = document.createElement("style");
+  style.dataset.canvasAppStyle = marker;
+  style.textContent = css;
+  document.head.append(style);
+  return () => style.remove();
+}
+
+// During mount:
+const disposeStyles = installStyles(STYLES, "acme-dashboard");
+const root = document.createElement("div");
+root.className = "acme-dashboard";
+container.append(root);
+return () => {
+  disposeStyles();
+  root.remove();
+};
+```
+
+If more than one page can mount concurrently, ref-count the marker or inject its stylesheet once in `activate` and remove it in the activation disposer.
+
+## Verify before delivery
+
+- Confirm extension markup uses a unique root class and no App CSS leaks outside it.
+- Confirm styles survive a real Canvas mount, route remount, disable/re-enable cycle, and host dark surface backgrounds.
+- Confirm `extension.js` has no unresolved CSS import, bare package import, extra CSS chunk, or Node global.
+- Run the Canvas extension static validator plus the App's lint, tests, and build.
+- Report whether the App uses direct host variables or an App-local Tailwind mapping, and list the tested states.