solverforge-ui

Frontend component library for SolverForge constraint-optimization applications. Emerald-themed, zero-framework, vendor-ready. One line to mount, zero npm in the runtime integration path, zero webpack.

// Cargo.toml
solverforge-ui = { path = "../solverforge-ui" }

// main.rs
let app = api::router(state)
    .merge(solverforge_ui::routes())      // serves /sf/*
    .fallback_service(ServeDir::new("static"));

<link rel="stylesheet" href="/sf/vendor/fontawesome/css/fontawesome.min.css">
<link rel="stylesheet" href="/sf/vendor/fontawesome/css/solid.min.css">
<link rel="stylesheet" href="/sf/sf.css">
<script src="/sf/sf.js"></script>

That's it. Every asset is compiled into the binary via include_dir!.

Shipped vs Planned

This repository keeps both shipped UI code and design exploration in the same tree.

Shipped features are the ones implemented in js-src/, or exposed as documented optional modules under static/sf/modules/, and described in the API reference below.
Planned or exploratory ideas may appear in CSS or wireframes before the public API is finished. Those should not be treated as supported integration surface until they are wired into a shipped asset and described in the README API reference.
When adding new surface area, update the JavaScript API, README, and runnable examples in the same change so the public contract stays explicit.

For production caching, versioned bundle filenames are also emitted as /sf/sf.<crate-version>.css and /sf/sf.<crate-version>.js. Those versioned files are served with immutable caching, while the stable sf.css and sf.js paths remain available for compatibility.

Screenshots

Planner123 — Gantt chart with split panes, project-colored bars, and constraint scoring:

Furnace Scheduler — Timeline rail with resource cards, temperature/load gauges, and positioned job blocks:

Philosophy

Every backend element has a corresponding UI element. The library grows alongside the solver. When you scaffold a new SolverForge project with solverforge new, it's already wired in.

Testing

Repository coverage now includes the embedded Rust asset routes plus Node-based frontend tests for backend adapters, focused solver lifecycle suites, and core component rendering. Use make test for the full suite, make test-quick for Rust doctests, Rust unit tests, frontend Node coverage, and browser smoke tests, or make test-frontend when you only want the JavaScript suite. Use make lint-frontend for ESLint on js-src/, tests/, and scripts/, or make lint to run the Rust and JavaScript lint surfaces together.

Quick Start

<body class="sf-app">
<script>
  var tabs = SF.createTabs({
    tabs: [
      { id: 'plan', content: '<div>Plan view</div>', active: true },
      { id: 'gantt', content: '<div>Gantt view</div>' },
    ],
  });
  document.body.appendChild(tabs.el);

  var backend = SF.createBackend({ type: 'axum' });

  var header = SF.createHeader({
    logo: '/sf/img/ouroboros.svg',
    title: 'My Scheduler',
    subtitle: 'by SolverForge',
    tabs: [
      { id: 'plan', label: 'Plan', icon: 'fa-list-check', active: true },
      { id: 'gantt', label: 'Gantt', icon: 'fa-chart-gantt' },
    ],
    onTabChange: function (id) { tabs.show(id); },
    actions: {
      onSolve: function () { solver.start(); },
      onPause: function () { solver.pause(); },
      onResume: function () { solver.resume(); },
      onCancel: function () { solver.cancel(); },
    },
  });
  document.body.prepend(header);

  var bar = SF.createStatusBar({ header: header, constraints: myConstraints });
  header.after(bar.el);

  var solver = SF.createSolver({
    backend: backend,
    statusBar: bar,
    onProgress: function (meta) {
      console.log('progress', meta.currentScore, meta.bestScore, meta.telemetry && meta.telemetry.movesPerSecond);
    },
    onSolution: function (snapshot) {
      render(snapshot.solution);
    },
    onPaused: function (snapshot, meta) {
      console.log('paused at snapshot', meta.snapshotRevision);
      render(snapshot.solution);
    },
    onComplete: function (snapshot, meta) {
      console.log('completed', meta.currentScore);
      render(snapshot.solution);
    },
  });
</script>
</body>

API Reference

Components

Factory	Returns	Description
`SF.createHeader(config)`	`HTMLElement`	Sticky header with logo, title, nav tabs, and optional solve/pause/resume/cancel/analyze actions
`SF.createStatusBar(config)`	`{el, bindHeader, updateScore, setLifecycleState, setSolving, updateMoves, updateConstraintDots, colorDotsByScore, colorDotsFromAnalysis}`	Score display + constraint dot indicators; pass `header` or call `bindHeader()` if it should toggle local solve/stop controls
`SF.createButton(config)`	`HTMLButtonElement`	Button with variant/size/icon/shape modifiers
`SF.createModal(config)`	`{el, body, open, close, setBody}`	Dialog with emerald gradient header, backdrop, Escape key
`SF.createTable(config)`	`HTMLElement`	Data table with headers and row click
`SF.createTabs(config)`	`{el, show}`	Tab panel container with instance-scoped tab switching
`SF.createFooter(config)`	`HTMLElement`	Footer with links and version
`SF.createApiGuide(config)`	`HTMLElement`	REST API documentation panel
`SF.showToast(config)`	`void`	Toast notification (auto-dismiss)
`SF.showError(title, detail)`	`void`	Danger toast shorthand
`SF.showTab(tabId, root?)`	`void`	Activate matching tab panels in every tab container, or only within `root` when provided

Unsafe HTML APIs (opt-in)

Default content is always text-rendered. Use these fields only with trusted HTML:

Factory	Unsafe HTML field
`SF.el(tag, attrs, ...)`	`unsafeHtml`
`SF.createModal(config)`	`unsafeBody`
`SF.createTabs(config)`	`tabs[].content.unsafeHtml`
`SF.createTable(config)`	`cells[].unsafeHtml`
`SF.gantt.create(config)`	`unsafePopupHtml`, `columns[].render(task).unsafeHtml`

Rail Scheduling

Factory	Returns	Description
`SF.rail.createTimeline(config)`	`{el, setModel, setViewport, expandCluster, destroy}`	Canonical dense scheduling timeline with sticky time header, sticky lane labels, synchronized horizontal viewport, drag-to-pan, configurable zoom presets, weekend shading, overlays, overview clustering, exact detailed geometry, and packed detailed lanes
`SF.rail.createHeader(config)`	`HTMLElement`	Low-level day/period header primitive for furnace-style rail layouts
`SF.rail.createCard(config)`	`{el, rail, addBlock, clearBlocks, setSolving, setUnassigned}`	Low-level resource lane primitive with identity, gauges, stats, and block rail
`SF.rail.addBlock(rail, config)`	`HTMLElement`	Low-level positioned block (task/job) inside a primitive rail
`SF.rail.addChangeover(rail, config)`	`HTMLElement`	Low-level diagonal-striped gap between primitive blocks
`SF.rail.createHeatmap(config)`	`HTMLElement \| null`	Optional low-level heatmap strip aligned with a rail card
`SF.rail.createUnassignedRail(tasks, onTaskClick)`	`HTMLElement`	Optional low-level unassigned-pill row

Gantt (Frappe Gantt)

Factory	Returns	Description
`SF.gantt.create(config)`	`{el, mount, setTasks, refresh, getChart, changeViewMode, highlightTask, destroy}`	Split-pane Gantt with grid table + Frappe Gantt chart

Solver Lifecycle

Factory	Returns	Description
`SF.createBackend(config)`	Backend adapter	HTTP or Tauri IPC transport
`SF.createSolver(config)`	`{start, pause, resume, cancel, delete, getSnapshot, analyzeSnapshot, isRunning, getJobId, getLifecycleState, getSnapshotRevision}`	Shared job lifecycle orchestration around typed runtime events, exact paused snapshots, retained analysis, and terminal cleanup

Startup streams may begin with either a scored progress event or a scored best_solution event. Consumers must not require progress to arrive first.

Canonical stream payloads:

{
  "eventType": "progress",
  "jobId": "job-42",
  "eventSequence": 1,
  "lifecycleState": "SOLVING",
  "currentScore": "0hard/-2soft",
  "bestScore": "0hard/-3soft",
  "telemetry": { "movesPerSecond": 12, "stepCount": 3200 }
}

{
  "eventType": "paused",
  "jobId": "job-42",
  "eventSequence": 4,
  "lifecycleState": "PAUSED",
  "snapshotRevision": 2,
  "currentScore": "0hard/-1soft",
  "bestScore": "0hard/-1soft",
  "telemetry": { "movesPerSecond": 0, "stepCount": 6400 }
}

{
  "eventType": "best_solution",
  "jobId": "job-42",
  "eventSequence": 2,
  "lifecycleState": "SOLVING",
  "snapshotRevision": 1,
  "currentScore": "0hard/-1soft",
  "bestScore": "0hard/-1soft",
  "telemetry": { "movesPerSecond": 15, "stepCount": 4200 },
  "solution": { "id": "job-42", "score": "0hard/-1soft" }
}

Runtime rules:

The first lifecycle event for a newly started solve may be progress or best_solution, but it must already be scored.
Backends that bootstrap startup state from a retained snapshot must not follow it with an identical startup best_solution duplicate.
progress is metadata-only. It must not carry the solution payload.
best_solution must include solution and snapshotRevision.
pause_requested does not imply that a checkpoint is ready yet.
paused, completed, cancelled, and failed are authoritative lifecycle events. SF.createSolver() syncs the retained snapshot before firing the corresponding callbacks.
deleteJob() is required for every backend passed to SF.createSolver(). It is the only supported cleanup path for retained jobs.
HTTP EventSource.onerror is transport state, not runtime lifecycle state. Reconnecting errors are ignored. A closed stream is surfaced through onError as an SSE transport error while preserving the last authoritative lifecycle, retained job id, score, metadata, and snapshot revision.
Only runtime lifecycle events or explicit status/snapshot synchronization can move the solver lifecycle. Transport interruption does not make Delete legal and does not replace SOLVING, PAUSED, or terminal runtime states with IDLE.
createJob() results are normalized before stream attachment. Non-empty strings, finite numbers including 0, and objects containing a scalar id, jobId, or job_id field become string job ids. Non-scalar or empty ids reject startup instead of being stringified.
start() never replaces a retained job. Even terminal retained jobs require a successful delete() before the next solve can start.
delete() is destructive backend cleanup for terminal retained jobs only. It waits for any in-flight terminal snapshot synchronization before cleanup, is not a local-only reset, and a failed deleteJob() call preserves the retained job id and terminal lifecycle state. COMPLETED and TERMINATED_BY_CONFIG jobs require successful terminal snapshot synchronization before deleteJob() is allowed; if the first terminal sync failed, delete() retries it once and rejects without backend deletion if the retry also fails.
pause() sends pauseJob() only from SOLVING; a pause requested while STARTING queues until the job id exists. PAUSE_REQUESTED blocks duplicate pause requests, and RESUMING does not allow pause.
resume() sends resumeJob() only from PAUSED.
User-facing Stop is visible during CANCELLING, but sends cancelJob() only from SOLVING, PAUSE_REQUESTED, PAUSED, or RESUMING; a cancel requested while STARTING queues until the job id exists. Activating Stop during CANCELLING may reattach a detached stream listen-only to observe the terminal event, but it must not send another backend cancel command.
The status bar uses currentScore as the live score during solving.
Missing or malformed typed lifecycle fields are ignored; they are not silently normalized into the contract.

Utilities

Function	Description
`SF.score.parseHard(str)`	Extract hard score from `"0hard/-42soft"`
`SF.score.parseSoft(str)`	Extract soft score
`SF.score.parseMedium(str)`	Extract medium score
`SF.score.getComponents(str)`	`{hard, medium, soft}`
`SF.score.colorClass(str)`	`"score-green"` / `"score-yellow"` / `"score-red"`
`SF.colors.pick(key)`	Tango palette color for any key (cached)
`SF.colors.project(index)`	`{main, dark, light}` from 8-color project palette
`SF.colors.reset()`	Clear the color cache
`SF.escHtml(str)`	HTML-escape a string
`SF.normalizeCreateJobId(raw)`	Normalize a create-job response to a string id, or `''` for invalid non-scalar ids
`SF.el(tag, attrs, ...children)`	DOM element factory

Button Variants

SF.createButton({ text: 'Solve',    variant: 'success' })   // white bg, emerald text
SF.createButton({ text: 'Stop',     variant: 'danger' })    // red bg, white text
SF.createButton({ text: 'Save',     variant: 'primary' })   // emerald-700 bg
SF.createButton({ text: 'Cancel',   variant: 'default' })   // gray border
SF.createButton({ icon: 'fa-gear',  variant: 'ghost', circle: true })
SF.createButton({ text: 'Settings', icon: 'fa-gear', variant: 'ghost', iconOnly: true })
SF.createButton({ text: 'Submit',   variant: 'primary', pill: true })
SF.createButton({ text: 'Delete',   variant: 'danger', outline: true })
SF.createButton({ text: 'Sm',       variant: 'primary', size: 'small' })

Rail Scheduling

SF.rail.createTimeline() is the canonical read-only scheduling surface. It accepts a normalized numeric model only; backend timestamp parsing and timezone policy stay outside the library. Every minute field and viewport boundary must already be an integer number of minutes. String timestamps, Date objects, numeric strings, and fractional minutes are rejected instead of being coerced inside the library. Malformed tick objects and overlay spans are rejected instead of being silently dropped during normalization. Layout density is derived from the actual timeline body viewport, not padded wrappers or outer card chrome. labelWidth is the preferred sticky-label width; supported embeds with a body viewport of 500px or wider compact that label column as needed to preserve at least 320px of visible schedule track. Detached timelines are supported: creating a timeline or calling setModel() before appending timeline.el queues a post-mount layout synchronization so the header, body, content width, and compact label width are recalculated once real viewport dimensions are available. The body viewport is the vertical scroll container for dense solved schedules; the sticky header keeps its native scrollbar hidden while horizontal scroll and drag-pan stay synchronized with the body. Use mode: 'overview' for scanable location or resource lanes, and mode: 'detailed' for precise per-person or per-assignment inspection. Overview blocks can carry additive summary metadata and expose the same detail via keyboard focus that hover reveals with a mouse. Detailed lanes use exact time geometry for rendered blocks. Adjacent intervals such as [60, 120] and [120, 180] remain visually disjoint on the same track, while true interval overlaps are packed onto separate track rows.

Timeline config:

title: optional toolbar title and region label; defaults to Scheduling timeline
subtitle: optional toolbar subtitle
label: optional sticky axis-corner label; defaults to Lane
labelWidth: optional sticky lane-label width in pixels; defaults to 280
zoomPresets: optional array containing any of 1w, 2w, 4w, and reset; defaults to all four presets, and [] omits the zoom controls for fixed-horizon app surfaces

Model shape:

model.axis: startMinute, endMinute, days[], ticks[], initialViewport
model.lanes[]: id, label, optional badges, optional stats, optional overlays, mode, items[]
items[]: id, startMinute, endMinute, label, optional meta, optional summary, tone, optional clusterId, optional detailItems[]
overlays[]: either numeric spans via startMinute/endMinute or full-day bands via dayIndex/dayCount

Additive overview summary contract:

summary.primaryLabel: optional aggregate block headline
summary.secondaryLabel: optional aggregate block subline
summary.count: optional explicit total count for the overview block
summary.openCount: optional explicit open or unassigned count
summary.toneSegments[]: optional additive tone-composition hint with { tone, count }

These fields are additive per field, not an all-or-nothing summary mode. If a group mixes summarized and unsummarized items, the library combines the explicit summary fields with derived count/open/tone data from the remaining grouped items. Use explicit summary when the app already knows the aggregate staffing signal it wants overview users to see first.

If a summary item overrides aggregate count beyond the number of concrete backing items the library can inspect, omitted openCount and omitted toneSegments remain unknown and are not rendered. In that case, provide summary.openCount and summary.toneSegments explicitly if you want those aggregate signals shown.

Integer-only fields remain integer-only:

all time-bearing minute fields on axis, days, ticks, items, overlays, and initialViewport
model.lanes[].overlays[].dayIndex
model.lanes[].overlays[].dayCount

If you want stable programmatic expansion through expandCluster(laneId, clusterId), provide clusterId on the overlapping overview items that should expand together. Each lane may produce at most one overview group for a given clusterId; reusing the same clusterId for disjoint groups is rejected as ambiguous input. Expanded overview clusters remain clickable inside the component and use the same block as the collapse affordance. The example below assumes small consumer-side helpers such as buildDays() and buildSixHourTicks() that normalize backend timestamps into numeric axis data.

var timeline = SF.rail.createTimeline({
  title: 'Scheduling timeline',
  label: 'Staffing lane',
  labelWidth: 280,
  zoomPresets: ['1w', '2w', '4w', 'reset'],
  model: {
    axis: {
      startMinute: 0,
      endMinute: 28 * 1440,
      days: buildDays(28),
      ticks: buildSixHourTicks(28),
      initialViewport: { startMinute: 0, endMinute: 14 * 1440 },
    },
    lanes: [
      {
        id: 'ward-east',
        label: 'By location · Ward East',
        mode: 'overview',
        badges: ['default'],
        overlays: [
          { dayIndex: 5, label: 'Unavailable', tone: 'red' },
          { dayIndex: 11, dayCount: 2, label: 'Desired', tone: 'emerald' },
        ],
        items: [
          {
            id: 'east-rush',
            clusterId: 'east-rush',
            startMinute: 360,
            endMinute: 1080,
            label: 'Monday intake surge',
            tone: 'blue',
            summary: {
              primaryLabel: 'Monday intake surge',
              secondaryLabel: 'ER intake · trauma hold · overflow beds',
              count: 24,
              openCount: 3,
              toneSegments: [
                { tone: 'blue', count: 15 },
                { tone: 'amber', count: 6 },
                { tone: 'rose', count: 3 },
              ],
            },
            detailItems: [
              { id: 'east-1', startMinute: 360, endMinute: 840, label: 'ER intake', meta: '8 clinicians', tone: 'blue' },
              { id: 'east-2', startMinute: 420, endMinute: 960, label: 'Trauma hold', meta: '6 clinicians', tone: 'amber' },
              { id: 'east-3', startMinute: 480, endMinute: 1080, label: 'Overflow beds', meta: '10 clinicians', tone: 'rose' },
            ],
          },
          { id: 'east-4', startMinute: 2 * 1440 + 360, endMinute: 2 * 1440 + 1080, label: 'Cardio block', meta: '5 clinicians', tone: 'emerald' },
        ],
      },
      {
        id: 'employee-ada',
        label: 'By employee · Ada',
        mode: 'detailed',
        badges: ['detailed'],
        items: [
          { id: 'ada-1', startMinute: 2 * 1440 + 360, endMinute: 2 * 1440 + 840, label: 'Primary shift', meta: 'Ward East', tone: 'amber' },
          { id: 'ada-2', startMinute: 2 * 1440 + 660, endMinute: 2 * 1440 + 1020, label: 'Handoff overlap', meta: 'Safety round', tone: 'amber' },
        ],
      },
    ],
  },
});
container.appendChild(timeline.el);

timeline.setViewport({ startMinute: 7 * 1440, endMinute: 21 * 1440 });
timeline.expandCluster('ward-east', 'east-rush');

Returned timeline API:

el
setModel(model)
setViewport(viewport)
expandCluster(laneId, clusterId | null)
destroy()

Low-Level Rail Primitives

Use these when you want to assemble a custom furnace-style resource rail manually instead of using the higher-level scheduling timeline.

var header = SF.rail.createHeader({
  label: 'Resource',
  labelWidth: 220,
  columns: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
});
container.appendChild(header);

var card = SF.rail.createCard({
  id: 'furnace-1',
  name: 'FORNO 1',
  labelWidth: 220,
  columns: 5,
  type: 'CAMERA',
  badges: ['TEMPRA'],
  gauges: [
    { label: 'Temp', pct: 85, style: 'heat', text: '850/1000°C' },
    { label: 'Load', pct: 60, style: 'load', text: '120/200 kg' },
  ],
  stats: [
    { label: 'Jobs', value: 12 },
    { label: 'Production', value: '840 kg' },
  ],
});
container.appendChild(card.el);

card.addBlock({
  start: 120,
  end: 360,
  horizon: 4800,
  label: 'ODL-2847',
  meta: 'Bianchi',
  color: 'rgba(59,130,246,0.6)',
  borderColor: '#3b82f6',
});

SF.rail.addChangeover(card.rail, { start: 360, end: 400, horizon: 4800 });
card.setUnassigned([{ id: 'late-queue', label: 'ODL-991' }]);
card.setSolving(true);

SF.rail.addBlock() keeps a 0.5% minimum rendered width by default for primitive rail visibility. Pass minWidthPct: 0 when a consumer needs exact interval geometry instead of a visibility floor.

Gauge styles: heat (blue→amber→red), load (emerald→amber→red), emerald (solid green). badges accepts either strings or { label, style } objects for extra resource metadata.

Gantt Chart

Interactive task scheduling with Frappe Gantt. Split-pane layout: task grid on top, SVG timeline chart on bottom. Drag to reschedule, resize to change duration, sortable grid columns, project-colored bars, dependency arrows, and pinned task styling.

<link rel="stylesheet" href="/sf/vendor/frappe-gantt/frappe-gantt.min.css">
<script src="/sf/vendor/frappe-gantt/frappe-gantt.min.js"></script>
<script src="/sf/vendor/split/split.min.js"></script>

var gantt = SF.gantt.create({
  gridTitle: 'Tasks',
  chartTitle: 'Schedule',
  viewMode: 'Quarter Day',
  splitSizes: [40, 60],
  columns: [
    { key: 'name', label: 'Task', sortable: true },
    { key: 'start', label: 'Start', sortable: true },
    { key: 'end', label: 'End', sortable: true },
    { key: 'priority', label: 'P', render: function (t) {
      return {
        unsafeHtml: '<span class="sf-priority-badge priority-' + t.priority + '">P' + t.priority + '</span>',
      };
    }},
  ],
  onTaskClick: function (task) { console.log('clicked', task.id); },
  onDateChange: function (task, start, end) { console.log('moved', task.id, start, end); },
});

gantt.mount('my-container');

gantt.setTasks([
  {
    id: 'task-1',
    name: 'Design review',
    start: '2026-03-15 09:00',
    end: '2026-03-15 10:30',
    priority: 1,
    projectIndex: 0,
    pinned: true,
    custom_class: 'project-color-0 priority-1',
    dependencies: '',
  },
  {
    id: 'task-2',
    name: 'Implementation',
    start: '2026-03-15 10:30',
    end: '2026-03-15 14:00',
    priority: 2,
    custom_class: 'project-color-0 priority-2',
    dependencies: 'task-1',
  },
]);

gantt.changeViewMode('Day');
gantt.highlightTask('task-1');

View modes: Quarter Day, Half Day, Day, Week, Month. Sortable headers are opt-in per column via sortable: true.

Backend Adapters

Axum (default)

var backend = SF.createBackend({ type: 'axum', baseUrl: '' });

Expects standard SolverForge REST endpoints:

POST /jobs — create a retained job
GET /jobs/{id} — get job summary/status
GET /jobs/{id}/status — get job status summary
GET /jobs/{id}/snapshot — get the latest or requested retained snapshot
GET /jobs/{id}/analysis — analyze the latest or requested retained snapshot
POST /jobs/{id}/pause — request an exact runtime-managed pause
POST /jobs/{id}/resume — resume from the retained checkpoint
POST /jobs/{id}/cancel — cancel a live or paused job
DELETE /jobs/{id} — delete a terminal retained job
GET /jobs/{id}/events — SSE stream
GET /demo-data/{name} — load demo dataset

Backend contract expectations:

Custom backends passed to SF.createSolver() must implement createJob(), streamJobEvents(), getSnapshot(), analyzeSnapshot(), pauseJob(), resumeJob(), cancelJob(), and deleteJob().
createJob() must resolve to a plain job id (non-empty string or finite number), or an object containing a scalar id, jobId, or job_id. Numeric 0 is a valid id and is normalized to "0".
Non-scalar createJob() ids such as arrays, nested objects, booleans, NaN, infinities, and empty strings are rejected before the solver attaches streams or performs snapshot/analysis calls.
Built-in HTTP and Tauri adapters also accept { data: { id } } response wrappers and normalize the id through the same scalar-only path.
getSnapshot() and analyzeSnapshot() accept an optional snapshotRevision. SF.createSolver() uses the exact revision from paused and terminal events when it syncs the retained state.
pauseJob() requests a pause. SF.createSolver().pause() resolves only after the authoritative paused event and snapshot sync complete.
resumeJob() resolves through the runtime event stream. SF.createSolver().resume() settles on the authoritative resumed event.
cancelJob() is the backend operation behind user-facing Stop. It settles through the runtime event stream, and SF.createSolver().cancel() resolves when the terminal event has been synchronized.
deleteJob() is destructive cleanup for terminal retained jobs only. SF.createSolver().delete() clears local retained state only after required terminal synchronization and this backend call both succeed.
Events passed into streamJobEvents() for a job should include one of the same identifiers if multiple solver runs are possible.
Tauri payloads are ignored only when they carry a different job id than the active run; id-less single-run updates still pass through.
Solver lifecycle events are canonical camelCase only: eventType, jobId, eventSequence, lifecycleState, snapshotRevision, currentScore, bestScore, telemetry, and solution where required.
eventType must be explicit. Supported values are progress, best_solution, pause_requested, paused, resumed, completed, cancelled, and failed.
Raw score-only progress payloads and implicit completion heuristics are not part of the supported stream contract.

Tauri

var backend = SF.createBackend({
  type: 'tauri',
  invoke: window.__TAURI__.core.invoke,
  listen: window.__TAURI__.event.listen,
  eventName: 'solver-update',
});

Generic fetch (Rails, etc.)

var backend = SF.createBackend({
  type: 'fetch',
  baseUrl: '/api/v1',
  headers: { 'X-CSRF-Token': csrfToken },
});

Optional Modules

Map (Leaflet)

<link rel="stylesheet" href="/sf/vendor/leaflet/leaflet.css">
<script src="/sf/vendor/leaflet/leaflet.js"></script>
<link rel="stylesheet" href="/sf/modules/sf-map.css">
<script src="/sf/modules/sf-map.js"></script>

var map = SF.map.create({ container: 'map', center: [45.07, 7.69], zoom: 13 });

map.addVehicleMarker({ lat: 45.07, lng: 7.69, color: '#10b981' });
map.addVisitMarker({ lat: 45.08, lng: 7.70, color: '#3b82f6', icon: 'fa-utensils' });
map.addStopNumber({ lat: 45.08, lng: 7.70, number: 1, color: '#3b82f6' });
map.drawRoute({ points: [[45.07, 7.69], [45.08, 7.70]], color: '#10b981' });
map.drawEncodedRoute({ encoded: 'encodedPolylineString', color: '#3b82f6' });
map.fitBounds();
map.highlight('#10b981');   // dim all routes except this color
map.clearHighlight();
map.clearRoutes();
map.clearStops();
map.clearMarkers();
map.clearAll();

SF.map.decodePolyline('_p~iF~ps|U...');  // Google polyline algorithm

Design System

Colors

Token	Hex	Usage
`--sf-emerald-500`	`#10b981`	Primary brand, success states
`--sf-emerald-600`	`#059669`	Primary dark
`--sf-emerald-700`	`#047857`	Primary buttons, links
`--sf-red-600`	`#dc2626`	Danger buttons, hard violations
`--sf-amber-500`	`#f59e0b`	Warnings, soft violations
`--sf-gray-50`	`#f9fafb`	Backgrounds
`--sf-gray-900`	`#111827`	Primary text

8 project colors for assignment: emerald, blue, purple, amber, pink, cyan, rose, lime.

Fonts

Space Grotesk (body, headings) — variable weight 300-700, self-hosted WOFF2
JetBrains Mono (code, scores, data) — variable weight 100-800, self-hosted WOFF2

Spacing

--sf-space-{0,1,2,3,4,5,6,8,10,12,16} — 0 to 4rem in quarter-rem increments.

Shadows

--sf-shadow-{sm,base,md,lg,xl,2xl} — elevation scale. --sf-shadow-emerald — colored shadow for branded elements.

Animations

sf-spin / sf-dot-pulse / sf-score-flash / sf-dialog-slide-in / sf-breathe / sf-slide-in / sf-fade-in / sf-late-glow

Project Structure

solverforge-ui/
├── Cargo.toml              # 2 deps: axum + include_dir
├── src/lib.rs              # routes() + asset serving
├── Makefile                # bundles css-src/ + js-src/ into sf.css + sf.js
├── .github/workflows/      # CI, release, and publish automation
├── css-src/                # 20 CSS source files (numbered for concat order)
│   ├── 00-tokens.css       #   design system variables
│   ├── 01-reset.css        #   box-sizing reset
│   ├── 02-typography.css   #   @font-face declarations
│   ├── 03-layout.css       #   .sf-app, .sf-main, tab panels
│   ├── 04-header.css       #   .sf-header
│   ├── 05-statusbar.css    #   .sf-statusbar + constraint dots
│   ├── 06-buttons.css      #   .sf-btn variants
│   ├── 07-modal.css        #   .sf-modal
│   ├── 08-table.css        #   .sf-table + constraint analysis table
│   ├── 09-badges.css       #   .sf-badge variants
│   ├── 10-cards.css        #   .sf-card, .sf-kpi-card
│   ├── 11-tooltip.css      #   .sf-tooltip
│   ├── 12-footer.css       #   .sf-footer
│   ├── 13-scrollbars.css   #   custom webkit scrollbars
│   ├── 14-animations.css   #   @keyframes + toast + api guide
│   ├── 15-rail-resources.css # resource cards, gauges, resource layout
│   ├── 16-rail-blocks.css  #   rail blocks, changeovers, unassigned styles
│   ├── 17-gantt-layout.css #   split layout, grid table, view controls
│   ├── 18-gantt-bars.css   #   Frappe bar overrides, pinned/highlighted bars
│   └── 19-rail-timeline.css #  canonical scheduling timeline
├── js-src/                 # 17 JS source files
│   ├── 00-core.js          #   SF namespace, escHtml, el()
│   ├── 01-score.js         #   score parsing
│   ├── 02-colors.js        #   Tango palette + project colors
│   ├── 03-buttons.js       #   createButton()
│   ├── 04-header.js        #   createHeader()
│   ├── 05-statusbar.js     #   createStatusBar()
│   ├── 06-modal.js         #   createModal()
│   ├── 07-tabs.js          #   createTabs(), showTab()
│   ├── 08-table.js         #   createTable()
│   ├── 09-toast.js         #   showToast(), showError()
│   ├── 10-backend.js       #   createBackend() — axum/tauri/fetch
│   ├── 11-solver.js        #   createSolver() — SSE state machine
│   ├── 12-api-guide.js     #   createApiGuide()
│   ├── 13-rail.js          #   low-level rail header, cards, blocks, changeovers
│   ├── 13a-rail-timeline.js #  canonical scheduling timeline
│   ├── 14-gantt.js         #   Frappe Gantt wrapper (split pane, grid, chart)
│   └── 15-footer.js        #   createFooter()
└── static/sf/              # Embedded assets (include_dir!)
    ├── sf.css              # concatenated from css-src/
    ├── sf.js               # concatenated from js-src/
    ├── img/                # SVG logo asset (ouroboros)
    ├── fonts/              # Space Grotesk + JetBrains Mono WOFF2
    ├── modules/            # optional: sf-map.js/css
    └── vendor/             # FontAwesome 6.5, Leaflet 1.9, Frappe Gantt, Split.js

Integration Paths

Project Type	How It Works
Axum	Add crate dep, call `.merge(solverforge_ui::routes())`
Tauri	Add crate dep, serve via Tauri's asset protocol or custom command
Rails	Copy `static/sf/` into `public/sf/`, reference in layouts
Any HTTP server	Copy `static/sf/`, serve as static files
`solverforge new`	Automatic — wired into generated project

Non-Rust Projects

The static/sf/ directory is self-contained. Copy it, git-submodule it, or symlink it into any project that serves static files:

# git submodule
git submodule add https://github.com/solverforge/solverforge-ui vendor/solverforge-ui
ln -s vendor/solverforge-ui/static/sf public/sf

Development

# Edit source files
vim css-src/06-buttons.css
vim js-src/03-buttons.js

# Rebuild concatenated files
make assets

# Run frontend lint
make lint-frontend

# Compile the crate (embeds updated assets)
cargo build

Release Workflow

Consumer integration stays npm-free. Maintainer release automation does not.

Current crate release: 0.6.5.
Keep CHANGELOG.md current as work lands.
Use RELEASE.md as the source of truth when preparing a public release.
Run make pre-release before tagging.
Runtime and application integration use only the bundled static assets and the Rust crate.
Version bump targets in Makefile currently use npx commit-and-tag-version.
The GitHub and Forgejo release workflows trigger only after the generated v* tag is pushed.
Release and publish validation otherwise run through Cargo and GitHub Actions.

If you are cutting a release locally, make sure Node.js with npx is available before using the bump-* targets. After the bump completes, push the release commit and tag with git push --follow-tags or an equivalent tag-push command so the release automation actually starts.

Package Verification

Use make package-verify to inspect the exact crate contents that would be published.

The verification step checks that required bundled assets and crate metadata are present, and that development-only sources such as css-src/, js-src/, scripts/, and screenshots are not shipped in the published crate.

Bundling writes both stable compatibility assets (static/sf/sf.css, static/sf/sf.js) and versioned assets (static/sf/sf.<version>.css, static/sf/sf.<version>.js).

Demo Fixtures

Runnable demo fixtures live in demos/.

demos/full-surface.html exercises the primary shipped component surface together.
demos/timeline.html is the focused dense scheduling example built with SF.rail.createTimeline(), including additive overview summaries, inline expand/collapse, exact detailed geometry, and synchronized drag-pan.
demos/timeline-dense.html is the repeatable 28-day, 100-lane, 1500-item dense validation fixture for one scrollable body viewport.
demos/rail.html focuses on the low-level rail primitives: resource cards, blocks, gauges, and changeovers.
make demo-serve serves the repository at http://localhost:8000/demos/ for local validation.
make test-browser runs browser-level smoke tests against the shipped demo fixtures and refreshes the timeline acceptance screenshots in screenshots/.
Run make browser-setup once on a machine to install the Playwright test dependency and Chromium.

Acknowledgments

solverforge-ui builds on these excellent open-source projects:

Project	Use	License	Link
Font Awesome Free	Icons (Solid subset)	CC BY 4.0 (icons), SIL OFL (fonts), MIT (code)	github
Frappe Gantt	Interactive Gantt chart	MIT	github
Split.js	Resizable split panes	MIT	github
Leaflet	Interactive maps (optional module)	BSD-2-Clause	github
Space Grotesk	Body typeface	SIL Open Font License 1.1	github
JetBrains Mono	Monospace typeface	SIL Open Font License 1.1	github
Axum	Rust web framework	MIT	github
include_dir	Compile-time file embedding	MIT	github

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.forgejo/workflows		.forgejo/workflows
.github/workflows		.github/workflows
css-src		css-src
demos		demos
js-src		js-src
screenshots		screenshots
scripts		scripts
src		src
static/sf		static/sf
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.versionrc.json		.versionrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
PRD.md		PRD.md
README.md		README.md
RELEASE.md		RELEASE.md
WIREFRAME.md		WIREFRAME.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

solverforge-ui

Shipped vs Planned

Screenshots

Philosophy

Testing

Quick Start

API Reference

Components

Unsafe HTML APIs (opt-in)

Rail Scheduling

Gantt (Frappe Gantt)

Solver Lifecycle

Utilities

Button Variants

Rail Scheduling

Low-Level Rail Primitives

Gantt Chart

Backend Adapters

Axum (default)

Tauri

Generic fetch (Rails, etc.)

Optional Modules

Map (Leaflet)

Design System

Colors

Fonts

Spacing

Shadows

Animations

Project Structure

Integration Paths

Non-Rust Projects

Development

Release Workflow

Package Verification

Demo Fixtures

Acknowledgments

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages