feat(gateway): extract gateway frontend into ironclaw_gateway crate with widget system

[ilblackdragon]

Summary

Extracts the gateway frontend into a dedicated ironclaw_gateway crate and adds the widget extension system, enabling users and companies to customize the UI from the workspace.

• Static assets moved to crates/ironclaw_gateway/static/ — app.js, style.css, index.html, i18n/*, theme-init.js, favicon.ico
• Embedded via crate — ironclaw_gateway::assets::* constants replace include_str!() in gateway handlers
• Layout configuration — LayoutConfig type with branding (title, colors), tab order, chat features, per-widget config. Stored as .system/gateway/layout.json in workspace.
• Widget system — WidgetManifest + WidgetSlot enum (Tab, ChatHeader, Sidebar, etc., though only Tab is currently mounted by the browser runtime). Widgets stored in workspace at .system/gateway/widgets/{id}/.
• CSS scoping — scope_css() auto-prefixes widget CSS with [data-widget="id"] for isolation; brace-depth-aware so nested @media / @supports / @container rules are scoped recursively while @keyframes bodies pass through opaque.
• Bundle assembly — assemble_index() injects layout config, widget scripts, scoped widget CSS, and branding into the base HTML; XSS-hardened against </script> and </style> breakouts in case-insensitive UTF-8-safe form.
• CSP nonce — injected <script> blocks carry a per-request CSP nonce via the NONCE_PLACEHOLDER sentinel; index_handler stamps a fresh nonce per response and emits a matching Content-Security-Policy: script-src 'nonce-…' header so the browser actually executes the inlined widget runtime.
• HTML cache — GatewayState::frontend_html_cache keys on the updated_at of .system/gateway/layout.json and .system/gateway/widgets/ (one cheap list() call), so the warm path skips reading every widget manifest / JS / CSS file.
• Frontend API — GET/PUT /api/frontend/layout, GET /api/frontend/widgets, GET /api/frontend/widget/{id}/{*file}. The {id} segment goes through component-based path-traversal validation (is_safe_segment / is_safe_relative_path).
• Browser widget API — IronClaw.registerWidget({ slot: "tab", … }) and IronClaw.registerChatRenderer({ id, match, render }) for inline rendering of structured data. Widgets get an IronClaw.api object with authenticated fetch, SSE event subscription, theme info, i18n, and navigation.

Workspace layout

All gateway state lives under .system/gateway/ in the workspace, alongside other .system/* subsystems being introduced in parallel work:

.system/gateway/
  README.md           # seeded on first boot from src/workspace/seeds/FRONTEND.md
  layout.json         # branding, tabs, chat features, per-widget config
  custom.css          # appended to /style.css
  widgets/{id}/
    manifest.json
    index.js
    style.css         # optional, auto-scoped

Stacked on

• feat(workspace): metadata-driven indexing/hygiene, document versioning, and patch #1723 (workspace metadata/versioning/patch)

New files

File	Purpose
crates/ironclaw_gateway/	New crate (Cargo.toml + 4 source files)
crates/ironclaw_gateway/static/	Moved from src/channels/web/static/
src/channels/web/handlers/frontend.rs	Layout + widget API handlers
src/workspace/seeds/FRONTEND.md	Customization guide seeded into the workspace

Test plan

• cargo fmt — clean
• cargo clippy --all --benches --tests --examples --all-features — zero warnings
• cargo test -p ironclaw_gateway — 46 unit tests + 1 doctest pass
• cargo test --lib -p ironclaw — 4238 passed
• Per-response CSP nonce verified by test_build_csp_with_nonce_includes_nonce_source and test_generate_csp_nonce_is_unique_and_hex
• Manual: gateway serves unchanged HTML with no workspace customizations
• Manual: write .system/gateway/layout.json to workspace → branding changes visible
• Manual: create widget (manifest + index.js) → new tab appears, browser executes widget under script-src 'nonce-…'

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces the ironclaw_frontend crate, which manages embedded static assets, layout configurations, and a widget extension system for the IronClaw web gateway. It includes logic for assembling the final served HTML by injecting branding and widget-specific scripts/styles, alongside new Axum handlers for layout CRUD and widget discovery. Feedback suggests reverting the Rust edition and version to stable releases and improving error handling by logging warnings when widget manifests fail to parse.

[gemini-code-assist]

The Rust edition and version are set to unreleased versions (edition = "2024", rust-version = "1.85"). This can cause build issues and unexpected behavior for developers using the stable Rust toolchain. It's recommended to use the latest stable edition (2021) and set rust-version to the project's actual Minimum Supported Rust Version (MSRV) that is a stable release.

Suggested change

	edition = "2024"
	rust-version = "1.85"
	edition = "2021"
	rust-version = "1.75"

[ilblackdragon]

The crate was renamed from ironclaw_frontend to ironclaw_gateway in a later commit, and the project standard is edition = "2024" / rust-version = "1.92" (every workspace member matches). Edition 2024 has been stable since Rust 1.85 (Feb 2025), so this is no longer an unreleased combination — it's the project baseline. Closing as a false positive.

[gemini-code-assist]

Errors from parsing a widget's manifest.json are silently ignored. While this prevents one broken widget from breaking the entire list, it makes debugging difficult for widget developers. Following repository patterns, when a resource cannot be parsed, it should be skipped with a warning log providing specific context about the failure to aid debugging.

            match serde_json::from_str::<WidgetManifest>(&doc.content) {
                Ok(manifest) => manifests.push(manifest),
                Err(e) => tracing::warn!("Skipping invalid widget manifest at '{}': {}", manifest_path, e),
            }

References

1. When a resource cannot be processed due to parsing errors, log a warning and skip it. Provide specific error context to provide semantically correct and clear error messages.

[ilblackdragon]

Already addressed. Both load_widget_manifests and load_resolved_widgets now route through read_widget_manifest (src/channels/web/handlers/frontend.rs:161), which logs a tracing::warn! with the manifest path and parse error before returning None:

Err(e) => {
    tracing::warn!(
        path = %manifest_path,
        error = %e,
        "skipping widget with invalid manifest"
    );
    return None;
}

Widget developers get the specific error context you asked for, and one broken widget still doesn't break the rest of the list.

[ilblackdragon]

Review comments addressed in fc32a31:

1. Edition/rust-version (high) — Fixed rust-version to 1.92 to match other crates. The edition = "2024" is correct and consistent with all other workspace crates.

2. Silent widget manifest errors (medium) — Now logs a warning with the path and parse error via tracing::warn! when a manifest fails to parse, instead of silently skipping.

Also fixed: missing license field for cargo-deny, ran cargo fmt.

[jasperan]

CI Fix for Formatting + Clippy Failures

The 5 failing CI jobs all trace to 4 root-cause errors in ironclaw_frontend. Here are the fixes:

1. cargo fmt (server.rs)

Run cargo fmt --all to fix 3 formatting diffs in src/channels/web/server.rs (function signature wrapping and format!() call layout).

2. Collapse nested if-let (bundle.rs:93)

// Before:
if let Some(ref custom_css) = bundle.custom_css {
    if !custom_css.trim().is_empty() {
        body_injections.push(format!("<style data-custom-css>{}</style>", custom_css));
    }
}

// After:
if let Some(ref custom_css) = bundle.custom_css
    && !custom_css.trim().is_empty()
{
    body_injections.push(format!("<style data-custom-css>{}</style>", custom_css));
}

3. Collapse triple nested if-let (bundle.rs:112-114)

// Before:
if let Some(ref title) = bundle.layout.branding.title {
    if let Some(start) = result.find("<title>") {
        if let Some(end) = result[start..].find("</title>") {
            let end = start + end + "</title>".len();
            result.replace_range(start..end, &format!("<title>{}</title>", title));
        }
    }
}

// After:
if let Some(ref title) = bundle.layout.branding.title
    && let Some(start) = result.find("<title>")
    && let Some(end) = result[start..].find("</title>")
{
    let end = start + end + "</title>".len();
    result.replace_range(start..end, &format!("<title>{}</title>", title));
}

4. while-let → for loop (widget.rs:77)

// Before:
let mut chars = css.chars().peekable();
while let Some(ch) = chars.next() {

// After:
let chars = css.chars();
for ch in chars {

(peekable() is unused, mut becomes unnecessary)

Bonus: pre-existing clippy lint (libsql/users.rs:984)

// Before:
assert!(stats.iter().find(|s| s.user_id == "bob").is_none());
// After:
assert!(!stats.iter().any(|s| s.user_id == "bob"));

[Copilot]

Pull request overview

Copilot reviewed 31 out of 40 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

read_layout_config treats any workspace.read() error as “missing file” and silently falls back to LayoutConfig::default(). That will hide real backend issues (e.g., WorkspaceError::IoError, SearchFailed) and make both /api/frontend/layout and the index assembly path ignore customizations without any signal. Consider matching on the error: return default only for DocumentNotFound, and warn! (or propagate as 500 for the API endpoint) for other error variants.

[ilblackdragon]

Fixed in 8065f94. You're right — the blanket Err(_) => LayoutConfig::default() masked IoError/SearchFailed/backend connectivity problems and dropped customizations without any operator signal.

Split the match in read_layout_config (src/channels/web/handlers/frontend.rs:45): WorkspaceError::DocumentNotFound stays silent (it's the common case — every page load hits this path for a workspace with no customizations), and every other variant now logs at warn! before the default fallback:

Err(WorkspaceError::DocumentNotFound { .. }) => LayoutConfig::default(),
Err(e) => {
    tracing::warn!(
        error = %e,
        path = LAYOUT_PATH,
        "workspace read failed — falling back to default layout \
         (customizations may be silently skipped)"
    );
    LayoutConfig::default()
}

Kept the infallible signature because the cache assembly path can't crash on workspace errors — the trade-off is that the API endpoint still returns a 200 with the default layout on backend failures instead of a 500, but backend issues now surface in logs instead of being invisible.

[Copilot]

load_widget_manifests swallows errors from workspace.list(WIDGETS_DIR) via unwrap_or_default(), so /api/frontend/widgets can return 200 [] even if listing fails due to an underlying workspace/backend error. Consider returning a Result (and letting the handler map to 500) or at least logging the error before falling back to an empty list.

[ilblackdragon]

Fixed in 8065f94. Both load_widget_manifests AND load_resolved_widgets used the same workspace.list().await.unwrap_or_default() pattern, so a real listing failure came out as 200 [] from /api/frontend/widgets and as "no widgets" on the index page — hiding the outage behind an empty-list response.

Both functions now match explicitly and log at warn! before the empty-list fallback (src/channels/web/handlers/frontend.rs):

let entries = match workspace.list(WIDGETS_DIR).await {
    Ok(entries) => entries,
    Err(e) => {
        tracing::warn!(
            error = %e,
            path = WIDGETS_DIR,
            "workspace list failed — returning empty widget list \
             (installed widgets may be silently skipped)"
        );
        Vec::new()
    }
};

An empty directory is still the silent default (the workspace returns an empty Vec for that case, not an error). Only genuine listing failures log now.

[Copilot]

frontend_widget_file_handler maps all workspace.read() failures to 404 Not Found. This will incorrectly return 404 for backend errors (e.g., DB connectivity / IO issues) and make operational debugging harder. Consider matching on WorkspaceError::DocumentNotFound for 404, and returning 500 for other error variants (while still logging details server-side).

[ilblackdragon]

Fixed in 8065f94. frontend_widget_file_handler now distinguishes 404 from 500 based on the error variant (src/channels/web/handlers/frontend.rs):

let doc = workspace.read(&path).await.map_err(|e| {
    use crate::error::WorkspaceError;
    match e {
        WorkspaceError::DocumentNotFound { .. } => {
            tracing::warn!(workspace_path = %path, "widget file not found");
            (StatusCode::NOT_FOUND, "Widget file not found".to_string())
        }
        other => {
            tracing::warn!(
                workspace_path = %path,
                error = %other,
                "widget file read failed (backend error)"
            );
            (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Failed to read widget file".to_string(),
            )
        }
    }
})?;

Backend failures (IoError, SearchFailed, connectivity) now show up as 500s so operational problems surface in status codes as well as logs. The client-facing bodies stay generic in both cases to preserve the path-enumeration hardening you noted in the surrounding block.

[Copilot]

The handler’s MIME type mapping falls back to text/plain for any non-(js/css/json/map) extension, but your docs/tests explicitly allow assets like assets/icon.svg. Serving SVG as text/plain can break rendering and may trigger content sniffing in some clients. Consider adding common types (e.g., image/svg+xml, image/png, image/jpeg, image/gif, image/webp, image/x-icon) or using a small MIME lookup (e.g., mime_guess) to keep widget assets usable.

[ilblackdragon]

Fixed in 8065f94. You're right — assets/icon.svg is explicitly allowed by both the regression test (widget_file_path_components_use_strict_charset) and the docs, but the MIME map was serving it as text/plain, which broke SVG rendering and would have triggered content sniffing on Chromium for the webfont files too.

Extended the match with the common widget asset types (src/channels/web/handlers/frontend.rs):

"js" | "mjs" => "application/javascript",
"css" => "text/css",
"json" => "application/json",
"map" => "application/json",
"svg" => "image/svg+xml",
"png" => "image/png",
"jpg" | "jpeg" => "image/jpeg",
"gif" => "image/gif",
"webp" => "image/webp",
"ico" => "image/x-icon",
"woff" => "font/woff",
"woff2" => "font/woff2",
"ttf" => "font/ttf",
"otf" => "font/otf",
_ => "text/plain",

Went with an explicit match rather than pulling in mime_guess — the list is short enough to be self-documenting and keeps the gateway's asset surface narrow (a widget author can't rely on serving arbitrary media types this way). text/plain is still the last-resort fallback for unknown extensions.

[Copilot]

The _wipe_customizations docstring says the gateway treats empty/unparseable widget files as “skip silently”, but read_widget_manifest() logs a warn! on JSON parse failure. Either adjust this comment (so it doesn’t promise silence) or update cleanup to remove/overwrite manifests in a way that avoids parse warnings if that’s important for test output clarity.

[ilblackdragon]

Fixed in 8065f94. You're right — read_widget_manifest logs a warn! on parse failure, so the "skip silently" promise in the docstring was wrong.

Updated _wipe_customizations in tests/e2e/scenarios/test_widget_customization.py:

memory_write accepts an empty body for non-layer paths, and the gateway's widget loader (read_widget_manifest) treats empty / unparseable widget manifests as "skip with a warn! log and continue" — no 500s, no index-page breakage — which is exactly the cleanup behavior we want without needing a real DELETE endpoint. The parse-failure warn lines are expected noise in the server log for the duration of this suite.

Kept the same cleanup mechanism (writing empty bodies) because it's the cleanest path we have without adding a DELETE endpoint purely for test plumbing — the warn lines are acceptable suite noise, now documented as such.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 40 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[serrrfirat]

Thorough paranoid architect review — this is an exceptionally well-defended PR. XSS escaping, CSP nonce rotation, multi-tenant leak guards, widget ID charset validation, path traversal protection, and same-origin enforcement are all solid. Approving.

A few non-blocking hardening suggestions were left as inline comments:

• Medium: frontend_widget_file_handler maps binary MIME types (PNG, WOFF2, etc.) but Workspace::read() returns String — binary widget assets would be corrupted. Text assets (JS/CSS/JSON/SVG) work fine, so no current production impact.
• Low: scope_css brace-depth parser doesn't handle CSS comments/string literals with {/} — worth a note in FRONTEND.md.
• Low: No per-widget size cap on JS/CSS loaded into the inline HTML bundle.
• Low: SSE event forwarding swallows JSON.parse errors silently — a console.warn would help debugging.
• Nit: escape_html_attr doesn't escape single quotes (safe today, all sites use double-quoted attrs).

None of these are blocking. Ship it. 🚢

[serrrfirat]

Medium — Correctness: This handler maps binary MIME types (image/png, font/woff2, font/ttf, etc.) but serves doc.content: String from Workspace::read(). Binary widget assets (images, fonts) would be silently corrupted because String is UTF-8 text.

No current production impact since primary widget assets (JS/CSS/JSON/SVG) are all text, but the MIME mapping advertises capabilities the handler cannot deliver. Options:

1. Remove binary MIME mappings and return 415 for binary extensions until a read_bytes() path exists
2. Add a comment marking them as aspirational (// TODO: requires binary workspace read)

Non-blocking.

[ilblackdragon]

Fixed in 3ca3e5a. You're right — Workspace::read() returns String (UTF-8 text), so binary payloads would be silently corrupted. Added a // TODO: requires read_bytes() comment on the binary MIME entries in the handler and documented the limitation in FRONTEND.md:

Binary assets: Widget files are served through the workspace text layer (Workspace::read()), which returns UTF-8 strings. Text-format assets (JS, CSS, JSON, SVG) work correctly. Binary assets (PNG, WOFF2, TTF, etc.) will be corrupted — host them externally or Base64-encode them into CSS/JS until a binary workspace read path is available.

Kept the MIME mappings rather than returning 415 so the browser at least sees the right Content-Type header — it surfaces the corruption instead of hiding it behind a text/plain content-sniffed interpretation.

[serrrfirat]

Low — Robustness: scope_css is brace-depth-based and does not handle CSS comments (/* } */) or string literals (content: "{") containing braces. Widget CSS with these patterns will produce malformed output.

The limitation is documented in the Rust doc comment, but the user-facing FRONTEND.md guide (which widget authors will actually read) does not mention it. Consider adding a note under the "Widgets" section:

Widget CSS must not contain { or } inside string literals or comments — the CSS scoping engine is a text transform, not a full parser.

Non-blocking.

[ilblackdragon]

Fixed in 3ca3e5a. Added a "CSS scoping caveat" note to src/workspace/seeds/FRONTEND.md:

CSS scoping caveat: Widget CSS is scoped via a brace-counting text transform, not a full CSS parser. Braces inside CSS comments (/* } */) or string literals (content: "{") will confuse the scoper and produce malformed output. Avoid { / } in comments and string values — use Unicode escapes (\\7B / \\7D) if you need literal braces in content: properties.

The Rust doc comment on scope_css already documented this, but widget authors reading the FRONTEND.md guide (their primary reference) would have missed it.

[serrrfirat]

Low — Robustness: No size guard on widget JS/CSS loaded into the HTML bundle. A single widget with a multi-MB index.js gets read into memory, scoped, escaped, and injected inline into the cached HTML — bloating every page response.

Consider a per-widget cap (e.g., 512KB JS / 256KB CSS) with a warn! log and skip for oversized files.

Non-blocking.

[ilblackdragon]

Fixed in 3ca3e5a. Added per-widget size caps in load_resolved_widgets (src/channels/web/handlers/frontend.rs):

• MAX_WIDGET_JS_BYTES = 512 KB — widget JS over this is skipped with a warn!
• MAX_WIDGET_CSS_BYTES = 256 KB — widget CSS over this is dropped with a warn!

The caps are generous enough for real-world widget bundles (a full charting library is ~250 KB minified) but stop a multi-MB file from ending up in the cached HTML. The warn! log names the widget and reports both the actual byte count and the cap so an operator can adjust or minify.

[serrrfirat]

Low — Robustness: The SSE event forwarding wrapper swallows JSON.parse errors in an empty catch (_) {}. If the gateway ever emits non-JSON SSE data, widget dispatching silently fails with no diagnostic.

} catch (_) {
  // Consider: console.warn("[IronClaw] SSE parse error for event", type, _);
}

Non-blocking.

[ilblackdragon]

Fixed in 3ca3e5a. Replaced the empty catch (_) {} with:

} catch (parseErr) {
  console.warn('[IronClaw] SSE parse error for event', type, parseErr);
}

Now surfaces non-JSON SSE data in the browser console so widget dispatch failures have a diagnostic. The gateway currently always emits JSON SSE data, but if that ever regresses this will be the first visible signal.