Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions .claude/skills/opsml-ui/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,34 @@ name: opsml-ui
description: Broad skill for building, editing, debugging, styling, and extending the OpsML UI in `crates/opsml_server/opsml_ui`. Use for Svelte 5 components, SvelteKit routes/layouts/load functions, internal `/routes/api` proxy endpoints, UI stores, Tailwind or Skeleton styling, card pages, Scouter dashboards, observability or trace views, agent or prompt interfaces, and general frontend bugfix or feature work inside the embedded OpsML frontend.
---

Work inside the existing `opsml_ui` architecture and visual language rather than treating this as a generic Svelte app.
Canonical skill for OpsML frontend work. The older `sveltekit-neobrutalism` skill is a legacy alias; use this skill as the source of truth for `crates/opsml_server/opsml_ui`.

Work inside the existing `opsml_ui` architecture and visual language rather than treating this as a generic Svelte app. OpsML is a dense developer tool, not a marketing site: build fast, scannable, task-oriented interfaces that expose operational details clearly.

Start by locating the feature boundary before editing:
- Read `references/working-map.md` to find the right feature area.
- Read `references/architecture.md` when changing routes, `+page.server.ts`, `+layout.server.ts`, `hooks.server.ts`, or `/routes/api` proxies.
- Read `references/design-system.md` when changing styling, layout, tokens, component chrome, or dashboard presentation.
- Read `references/sveltekit-patterns.md` when changing TypeScript logic, runes, server loads, API typing, or reusable helpers.

Then load only the topic references needed for the task:
- BFF/data-loading, server routes, load functions, invalidation, auth/session boundaries: read `references/sveltekit-architecture.md` and, for legacy route notes, `references/architecture.md`.
- Svelte component state, runes, snippets, effects, `.svelte.ts` modules, and legacy Svelte anti-patterns: read `references/svelte5-patterns.md` and, for shorter local patterns, `references/sveltekit-patterns.md`.
- Large tables, traces, files, charts, pagination, virtualization, search/filtering, and payload budgets: read `references/data-performance.md`.
- Developer workflow UX, registries, observability, trace inspection, filters, drilldowns, empty/loading/error states: read `references/developer-ux.md`.
- Tailwind v4, Skeleton, OpsML theme tokens, dark mode, icons, semantic color rules: read `references/theming.md` and, for short local rules, `references/design-system.md`.
- Vitest, Svelte Testing Library, pure utility tests, build/manual checks, accessibility and performance checks: read `references/testing-verification.md`.

Follow these repo-specific rules:
- Keep data fetching server-side by default. Prefer `+page.server.ts`, `+layout.server.ts`, and server helpers under `src/lib/server/`.
- Reuse the BFF shape already in the app. If a component needs backend access, prefer an internal SvelteKit `/routes/api/...` endpoint plus a server helper instead of calling the Rust backend directly from the browser.
- Reuse route constants from `src/lib/components/api/routes.ts` before introducing new path strings.
- Preserve OpsML theme tokens and brutalist interaction patterns. Do not introduce arbitrary hex colors, soft shadows, glassmorphism, or generic grayscale borders.
- Use `primary-*`, `secondary-*`, and `tertiary-*` for neutral UI categories. Reserve `success-*`, `warning-*`, and `error-*` for actual state, feedback, risk, or failure semantics.
- Keep types close to the feature unless they are clearly shared by multiple areas.
- Preserve the current auth flow in `src/hooks.server.ts` and `src/lib/server/auth/validateToken.ts`.
- Use `$derived(expression)` or `$derived.by(() => expression)` for derived state and keep derived values side-effect free.
- Use `$effect` mainly for external side effects such as browser APIs, observers, Chart.js, CodeMirror, imperative subscriptions, and request side effects.
- Prefer server-backed pagination, filtering, sorting, and aggregation for large remote datasets.
- Use `VirtualScroller.svelte` or `@tanstack/svelte-virtual` for large scrollable views.
- Do not add new UI libraries unless the user explicitly asks.

When making changes, inspect in this order:
1. The route entrypoint (`+page.svelte`, `+page.ts`, `+page.server.ts`, `+layout.*`)
Expand Down
7 changes: 7 additions & 0 deletions .claude/skills/opsml-ui/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
interface:
display_name: "OpsML UI"
short_description: "Work on the OpsML SvelteKit UI."
default_prompt: "Use $opsml-ui to edit, debug, style, or extend the OpsML UI in crates/opsml_server/opsml_ui."

policy:
allow_implicit_invocation: true
101 changes: 101 additions & 0 deletions .claude/skills/opsml-ui/references/data-performance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Data Performance

## Table Of Contents

- Source files to inspect
- Decision rules
- Pagination and filtering
- Virtualization
- Search and derived state
- Charts
- Files, code, and markdown
- Request cancellation and budgets
- Anti-patterns
- Official references

## Source Files To Inspect

- `crates/opsml_server/opsml_ui/src/lib/components/utils/VirtualScroller.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/trace/TraceInfiniteScroll.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/trace/TraceTable.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/trace/MetricChart.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/files/CodeViewer.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/files/fileSizeManager.svelte.ts`
- `crates/opsml_server/opsml_ui/src/routes/api/card/registry/page/+server.ts`
- `crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/+server.ts`

## Decision Rules

- If a dataset is remote and can grow beyond one screen, assume server-backed pagination, filtering, and sorting.
- If a list renders more than a few hundred rows, use virtualization or pagination before adding richer cells.
- If a row opens heavy detail, lazy-load the detail panel rather than attaching all nested content to every row.
- If a chart has more points than pixels, aggregate or downsample server-side or in a utility before rendering.
- If content can be very large, show a preview and require explicit user action for full content.

## Pagination And Filtering

- Prefer cursor or keyset pagination for trace streams, logs, events, and registry pages where ordering matters.
- Keep page sizes modest. OpsML trace flows commonly use limits around 50 and retain a bounded client window.
- Send search terms, filters, tags, sort fields, time ranges, and cursor values to BFF endpoints.
- Return enough cursor metadata for next and previous navigation.
- Keep empty result states distinct from backend failure.
- Do not fetch all registry cards, traces, spans, alerts, or files only to filter in Svelte.

## Virtualization

- Use `VirtualScroller.svelte` for fixed-height rows and bidirectional infinite scroll.
- Use `@tanstack/svelte-virtual` when variable list behavior or library ergonomics fit better than the local scroller.
- Provide stable keys such as `trace_id`, `uid`, or a composite key.
- Keep row height stable. Expand details in a side panel or below a selected row, not inside every virtualized row.
- Use overscan intentionally. Too little causes blanking; too much defeats virtualization.
- Preserve scroll anchors when prepending data, as `VirtualScroller.svelte` does.

## Search And Derived State

- Debounce user text input when it triggers network requests or expensive transforms.
- For small local lists, a derived search/sort is fine.
- For large arrays, avoid recreating full sorted and filtered copies on every keystroke. Move the operation server-side or into a bounded derived view model.
- Keep filter chips and active filter state typed so the request payload is stable.
- Avoid template-level calls to expensive formatting for every cell. Precompute row view models for dense tables.

## Charts

- Use existing Chart.js wrappers and chart utility builders.
- Destroy Chart.js instances on component teardown and before recreation.
- Recreate or update charts when theme tokens change.
- Use backend bucket intervals that match the selected time range.
- Prefer aggregated series for dashboards: counts, latency percentiles, error rates, cost, tokens, or drift summaries.
- Keep zoom/reset controls visible and keyboard reachable.

## Files, Code, And Markdown

- Follow `CodeViewer.svelte`: preview large files, disable expensive highlighting for very large content, and use bounded scroll containers.
- Do not render huge markdown or code blobs unbounded in the page.
- For tree views, lazy-load folders or file contents when selected.
- For JSON, avoid formatting very large payloads on every render. Format once or preview first.

## Request Cancellation And Budgets

- Cancel stale requests when users rapidly change filters, time ranges, or search text.
- Ignore out-of-order responses using a request id when cancellation is not available.
- Establish budgets before implementing:
- initial payload count and approximate byte size
- max client-retained rows
- row height and expected visible row count
- chart point count per series
- acceptable refetch frequency
- Use loading states that preserve layout size, especially in dashboards and tables.

## Anti-Patterns

- Client-side filtering of unbounded trace or registry datasets.
- Rendering all spans, events, attributes, and payloads for every trace row.
- Rebuilding charts without destroying old instances.
- Formatting large JSON or markdown in markup.
- Infinite scroll without a max retained item window.
- Fetching facets, metrics, rows, and details sequentially when they can be parallel or server-aggregated.

## Official References

- SvelteKit performance: https://svelte.dev/docs/kit/performance
- SvelteKit load: https://svelte.dev/docs/kit/load
7 changes: 7 additions & 0 deletions .claude/skills/opsml-ui/references/design-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ Do not introduce:
- `opsml-theme.css` defines color scales and theme variables
- `src/app.css` defines font, shadow, interaction, and utility patterns

## Palette Semantics
- Use `primary-*`, `secondary-*`, and `tertiary-*` for neutral categories such as metadata, tags, linked resources, schemas, parameters, extras, and configuration.
- Reserve `success-*` for actual positive state or completion feedback.
- Reserve `warning-*` for caution, risk, pending/degraded state, or user attention.
- Reserve `error-*` for failures, destructive outcomes, validation errors, or errored runtime state.
- Do not color neutral section icons with `success-*`, `warning-*`, or `error-*` just to add variety.

## Styling rules by context
- Dense dashboards and tables:
- favor clear structure, small shadows, restrained backgrounds
Expand Down
96 changes: 96 additions & 0 deletions .claude/skills/opsml-ui/references/developer-ux.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Developer UX

## Table Of Contents

- Product posture
- Navigation and information hierarchy
- Registry and card views
- Observability and trace workflows
- Files and artifacts
- Filters and drilldowns
- Empty, loading, and error states
- Keyboard and copy workflows
- Anti-patterns

## Product Posture

OpsML is a workbench for technical users. The UI should help users answer concrete questions:

- What exists?
- What changed?
- What failed?
- Where did this model, data card, prompt, service, trace, or alert come from?
- What should I inspect or do next?

Prioritize scan speed, stable layout, and clear operational metadata over decorative composition.

## Navigation And Information Hierarchy

- Preserve the existing app shell and Sidebar route model.
- Keep major resources under predictable groups: spaces, models, data, agents, experiments, services, observability.
- Use tabs for sibling views of the same entity, not unrelated workflows.
- Prefer split panes or side drawers for inspect-and-return workflows such as trace details and file previews.
- Keep breadcrumbs, entity names, versions, spaces, registry type, and status visible near the top of detail views.

## Registry And Card Views

- Registry pages should favor searchable, filterable lists with compact metadata.
- Show identity fields first: space, name, version, UID, registry type.
- Keep actions predictable: open, copy UID/path, favorite, compare, view files, view monitoring.
- Use status badges for functional state, not decoration.
- Make version navigation efficient. Users should not lose context when paging through versions.

## Observability And Trace Workflows

- Observability views should answer: volume, latency, errors, cost/tokens, service/model, and time range.
- Put filters close to results: time range, service, namespace, version, status, operation, model, tags.
- Keep selected trace detail adjacent to the trace list. Avoid full-page navigation for every trace inspection unless a shareable URL is required.
- In trace details, prioritize waterfall timing, status/error, model/tool calls, input/output previews, attributes, events, and resource metadata.
- Use lazy panels for verbose payloads and nested span details.
- Always provide a route or query param for shareable trace context when the workflow benefits from collaboration.

## Files And Artifacts

- Use a file tree plus detail pane for repository-like browsing.
- Show file size and type before rendering expensive content.
- Preview large files and require an explicit action for full content.
- Provide copy actions for paths, identifiers, JSON fragments, code snippets, and URLs.
- Keep binary/image/file-not-supported states direct and actionable.

## Filters And Drilldowns

- Active filters should be visible as removable chips or a compact summary.
- Filter changes should have immediate UI feedback and predictable refetch behavior.
- Expensive filters should be server-backed and debounced.
- Facets should reflect the current time range and resource context.
- Drilldowns should preserve the parent context, usually with a side panel, nested route, or query param.

## Empty, Loading, And Error States

- Empty states should name the current scope and suggest the next useful adjustment.
- Loading states should preserve panel dimensions and avoid reflow.
- Error states should distinguish:
- no data
- service disabled
- unauthorized
- network/backend failure
- malformed response
- Retry actions should invalidate or refetch the smallest useful scope.
- Do not hide partial data because one secondary request failed. Render available data and show a localized warning.

## Keyboard And Copy Workflows

- Use real buttons and links so keyboard navigation works without extra ARIA.
- Give icon-only buttons an accessible label.
- Keep focus visible against both light and dark themes.
- Provide copy actions for technical identifiers users need in issues, logs, or terminals.
- Preserve selection after refresh when possible.

## Anti-Patterns

- Marketing-style hero sections for operational tools.
- Big decorative cards that push data below the fold.
- Modal-only workflows for routine inspection.
- Hiding errors behind generic "something went wrong" copy.
- Tables with unstable row height, shifting columns, or unbounded cells.
- Requiring users to navigate away just to inspect a payload, span, or file.
97 changes: 97 additions & 0 deletions .claude/skills/opsml-ui/references/svelte5-patterns.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Svelte 5 Patterns

## Table Of Contents

- Source files to inspect
- Runes
- Props, snippets, and callbacks
- Effects and lifecycle
- Shared state
- Anti-patterns
- Official references

## Source Files To Inspect

- `crates/opsml_server/opsml_ui/src/lib/components/utils/VirtualScroller.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/nav/Sidebar.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/settings/theme.svelte.ts`
- `crates/opsml_server/opsml_ui/src/lib/components/files/CodeViewer.svelte`
- `crates/opsml_server/opsml_ui/src/lib/components/trace/MetricChart.svelte`

## Runes

- Use `$state` for local mutable component state.
- Use `$derived(expression)` for simple values that can be computed from current state and props.
- Use `$derived.by(() => expression)` when the derivation needs branching or several statements.
- Read derived values directly in script and markup.
- Keep derived state pure. Derivations should not fetch, mutate unrelated state, subscribe, or touch the DOM.
- Use stable keys in `{#each}` blocks for rows, traces, cards, and filter chips.

Example:

```svelte
<script lang="ts">
let selectedId = $state<string | null>(null);

const selected = $derived(
rows.find((row) => row.id === selectedId) ?? null
);

const sortedRows = $derived.by(() => {
const copy = rows.slice();
copy.sort((a, b) => a.name.localeCompare(b.name));
return copy;
});
</script>

{#each sortedRows as row (row.id)}
<button type="button" onclick={() => (selectedId = row.id)}>
{row.name}
</button>
{/each}
```

## Props, Snippets, And Callbacks

- Type props with a local `type Props` or interface when the prop shape is non-trivial.
- Use callback props for parent-owned state, for example `onSelect`, `onChange`, `onRefresh`.
- Do not mutate props directly. Ask the parent to update state.
- Use snippets for repeated cell/detail rendering, as `VirtualScroller.svelte` does with `children`.
- Prefer semantic elements with `type="button"` over clickable `div` wrappers.

## Effects And Lifecycle

- Use `onMount` for browser-only APIs: DOM measurement, observers, local storage setup, media query listeners, and client-only initialization.
- Use `$effect` for external side effects: Chart.js lifecycle, CodeMirror setup, request side effects, imperative subscriptions, or syncing with browser APIs.
- Return cleanup functions for observers, event listeners, and third-party instances.
- Avoid using effects to copy derived values into state.
- When an effect fetches, guard stale responses with cancellation, a request token, or `AbortController`.

OpsML examples:

- `MetricChart.svelte` uses effects to reset zoom and recreate Chart.js instances when config or theme changes.
- `theme.svelte.ts` gates browser-only local storage and media query behavior with `browser`.
- `VirtualScroller.svelte` uses `onMount` and `ResizeObserver` for container measurement.

## Shared State

- Use `.svelte.ts` modules for small, cohesive client-side state such as theme, time range, or UI preferences.
- Keep shared state APIs narrow: getters plus purposeful actions.
- Do not make a global store for page-specific state that should reset on route changes.
- Persist only state users expect to survive navigation.

## Anti-Patterns

- Legacy reactive labels for new code.
- Legacy event directives in new code.
- Broad untyped prop bags.
- Large components that mix fetch orchestration, filtering, chart setup, modal state, and rendering.
- Effects that exist only to keep two pieces of local state in sync.
- DOM querying when `bind:this` or component state is enough.

## Official References

- Svelte derived state: https://svelte.dev/docs/svelte/$derived
- Svelte effects: https://svelte.dev/docs/svelte/$effect
- Svelte props: https://svelte.dev/docs/svelte/$props
- Svelte snippets: https://svelte.dev/docs/svelte/snippet
Loading
Loading