docs: Document the model visualization contract (service-module + platform layers)

docs/src/modules/ROOT/nav.adoc

@@ -27,6 +27,7 @@
 *** xref:running-timefold-solver/service/constraint-overrides.adoc[Constraint weights]
 *** xref:running-timefold-solver/service/demo-data.adoc[leveloffset=+1]
 *** xref:running-timefold-solver/service/exposing-metrics.adoc[leveloffset=+1]
+*** xref:running-timefold-solver/service/visualization.adoc[leveloffset=+1]
 ** xref:running-timefold-solver/library/library-integration.adoc[As a library]
 *** xref:running-timefold-solver/library/configuration.adoc[leveloffset=+1]
 *** xref:running-timefold-solver/library/constraint-overrides.adoc[Constraint weights]
@@ -43,6 +44,7 @@
 ** xref:deploying-to-platform/guide.adoc[Guide]
 ** xref:deploying-to-platform/model-metadata.adoc[leveloffset=+1]
 ** xref:deploying-to-platform/metrics.adoc[leveloffset=+1]
+** xref:deploying-to-platform/visualization.adoc[leveloffset=+1]
 
 * Optimization algorithms
 ** xref:optimization-algorithms/overview.adoc[Overview]

docs/src/modules/ROOT/pages/deploying-to-platform/model-metadata.adoc

@@ -193,6 +193,4 @@ See https://docs.timefold.ai/timefold-platform/latest/how-tos/configuration-para
 [#_visualization]
 == Visualization
 
-There is currently no dedicated mechanism for adding a custom visualization UI for your model's solution on the platform.
-Consumers see the raw solution data and the generic score analysis view.
-This is an open area of the platform, so expect it to evolve in future releases.
+See xref:deploying-to-platform/visualization.adoc[] for how to add a custom visualization UI for your model's solution on the platform, instead of consumers only seeing the raw solution data and the generic score analysis view.

docs/src/modules/ROOT/pages/deploying-to-platform/visualization.adoc

@@ -0,0 +1,97 @@
+[#_platform_visualization]
+= Visualization
+:description: How a model's custom visualization UI is embedded and driven once deployed to Timefold Platform.
+:doctype: book
+:sectnums:
+:icons: font
+
+A model's solution can have a custom visualization UI, rendered inside Timefold Platform as an iframe, instead of consumers only seeing the raw solution data or the generic score analysis view.
+
+include::_preview-note.adoc[]
+
+[CAUTION]
+====
+This page documents how visualization works today, based directly on the current platform implementation.
+The contract described here, including iframe sizing, refresh behavior, asset paths, and page-announcement metadata, is still evolving and may change as the platform's visualization support matures, possibly without a smooth migration path.
+====
+
+[#_building_the_ui]
+== Building the UI
+
+The UI itself is the same set of static files described in xref:running-timefold-solver/service/visualization.adoc[], placed under `src/main/resources/META-INF/resources`.
+Once deployed, the platform repackages and serves these files under a `ui/` prefix, so the entry point the platform loads must be exactly `ui/index.html`.
+
+Asset paths under this prefix are single-segment only today: `ui/main.js` is servable, but `ui/assets/main.js` is not.
+Flatten your build output into a single directory, without subfolders.
+
+[#_iframe_embedding]
+== How the platform embeds the UI
+
+The platform renders `ui/index.html` inside a fixed-size iframe, sized by the platform's own layout, with no auto-grow or resize mechanism.
+
+Design your UI for a fixed viewport, or handle any overflow or scrolling yourself within that fixed area.
+
+[#_calling_your_api_from_the_iframe]
+== Calling your model's API from inside the iframe
+
+The platform injects the following query parameters into the iframe's `src` URL:
+
+[cols="1,3", options="header"]
+|===
+| Parameter | Purpose
+
+| `onPlatform`
+| Present when the UI is running embedded in the platform, absent when the UI is opened directly.
+
+| `runId`
+| The identifier of the dataset being viewed.
+
+| `tenantId`
+| The identifier of the tenant the dataset belongs to.
+
+| `apiUrl`
+| The base URL to use for calls to your model's API.
+
+| `apiKey`
+| The API key to use for calls to your model's API.
+|===
+
+Read `apiUrl` from `window.location.search`, strip any trailing slash, and prepend it to your own API calls, so they're routed correctly regardless of where the platform proxies from.
+Append the path your model's own REST API is served under — the same path you'd hit locally, as described in xref:running-timefold-solver/service/visualization.adoc#_calling_your_api[Calling your REST API from the UI].
+Only the base changes between running locally and running embedded in the platform.
+
+[#_refreshing_while_solving]
+== Refreshing while solving
+
+The platform doesn't push updates into the iframe or refresh it automatically.
+Your UI needs to poll its own status or solution endpoint on an interval, and stop polling once the dataset's status leaves the active or solving set.
+
+[#_error_reporting]
+== Error reporting
+
+The platform automatically injects a small error-forwarding script into the served HTML.
+This script turns uncaught JavaScript errors and unhandled promise rejections into a `postMessage` call, which the platform surfaces to the user as an alert in its own UI.
+
+Don't rely solely on `console.error` to signal failure: uncaught errors and unhandled promise rejections are what actually surface to the end user.
+Anything you only log to the console stays invisible to them.
+
+[#_announcing_visualization_pages]
+== Announcing visualization pages
+
+A model can offer multiple types of visualization, for example a map, a table, and a Gantt chart, and declares each one so the platform knows what to offer users and how to label and icon it. Declare pages through build-time configuration:
+
+[source,properties,options="nowrap"]
+----
+timefold.model.visualization.pages[0].key=map
+timefold.model.visualization.pages[0].icon=TbMap
+timefold.model.visualization.pages[0].label=Map
+timefold.model.visualization.pages[1].key=gantt
+timefold.model.visualization.pages[1].icon=TbChartGantt
+timefold.model.visualization.pages[1].label=Gantt chart
+----
+
+Each declared page has three required fields; omitting any of them fails the build.
+
+- `key`: a stable identifier for the page.
+- `icon`: an icon name from https://tabler.io/icons[Tabler Icons].
+- `label`: the human-readable name shown to users.

docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc

@@ -479,5 +479,6 @@ Since this is a "Getting Started" guide, not everything is covered yet.
 
 ** How to enrich your model with xref:running-timefold-solver/service/modeling-changes.adoc[model enrichment].
 ** How to configure your xref:running-timefold-solver/service/rest-api.adoc[REST API] with validations, custom endpoints, etc.
+** How to xref:running-timefold-solver/service/visualization.adoc[build a custom visualization UI] for your model's solution.
 ** How to xref:deploying-to-platform/guide.adoc[deploy this model to Timefold Platform].
-** How to xref:deploying-to-platform/metrics.adoc[use input and output metrics] to make platform features like solve graphs, comparison, and Insights more useful.
+** How to xref:deploying-to-platform/metrics.adoc[use input and output metrics] to make platform features like solve graphs, comparison, and Insights more useful.

docs/src/modules/ROOT/pages/running-timefold-solver/service/visualization.adoc

@@ -0,0 +1,57 @@
+[#_visualization]
+= Visualization
+:page-aliases: service/visualization.adoc
+:description: How to build a custom visualization UI for your model and serve it locally.
+:doctype: book
+:sectnums:
+:icons: font
+
+A model's solution is often easier to understand as a rendered UI than as raw JSON.
+This page describes how to build a custom visualization UI for your model and serve it from the service module while running locally.
+
+See xref:deploying-to-platform/visualization.adoc[] for how this same UI is embedded once your model is deployed to Timefold Platform.
+
+[#_serving_a_ui_locally]
+== Serving a UI locally
+
+Any static file placed under `src/main/resources/META-INF/resources` is served by Quarkus at the site root.
+For example, an `index.html` and `app.js` placed there are served at `http://localhost:8080/index.html` and `http://localhost:8080/app.js`.
+
+This static-resource handling is independent of your REST API path configuration: the UI files and the API endpoints are served from the same Quarkus instance, but the UI does not sit under whatever `@Path` your `ModelRest` interface declares.
+
+[#_ui_support_property]
+== Enabling the UI in the model descriptor archive
+
+Whether the archive generated around your xref:deploying-to-platform/guide.adoc#_what_happens_on_deploy[model descriptor] (`model-descriptor.zip`) bundles a UI is controlled by the build-time `timefold.model.ui-support` property, which accepts one of two values:
+
+- `NONE`: no UI is bundled.
+- `APP_JS`: the files under `src/main/resources/META-INF/resources` are bundled as the model's UI.
+
+If you don't set this property explicitly, it's auto-detected: if `src/main/resources/META-INF/resources` exists and contains at least one file, `APP_JS` is used; otherwise, `NONE` is used.
+
+[#_tips]
+== Tips
+
+[#_relative_asset_paths]
+=== Use relative asset paths
+
+When deployed to Timefold Platform, the same `META-INF/resources` files are repackaged and served under a `ui/` prefix instead of the site root (see xref:deploying-to-platform/visualization.adoc[]).
+A root-absolute reference like `<script src="/app.js">` breaks once moved under that prefix; a relative one like `<script src="./app.js">` still resolves correctly.
+Use relative asset paths in your `index.html` for this reason.
+
+[#_cors]
+=== Enable CORS for external dev servers
+
+The service module doesn't configure CORS for you.
+To run your UI on a separate dev server (Vite, webpack, ...), add: `quarkus.http.cors=true`.
+
+See the https://quarkus.io/guides/http-reference#cors-filter[Quarkus CORS guide] for how to restrict allowed origins, methods, or headers.
+
+[#_calling_your_api]
+== Calling your REST API from the UI
+
+Your UI calls your model's REST API the same way any other client would.
+
+Open the Swagger UI at `http://localhost:8080/q/swagger-ui/`, introduced in xref:quickstart/service/getting-started.adoc[Getting started: building a service], to check the exact path, rather than assuming a fixed prefix.
+
+See xref:deploying-to-platform/visualization.adoc[] for how to target your API from inside the platform's iframe.