# Models ## Purpose Models is a compact share view for comparing three curated AI model usage values. The chart and legend are the center of the experience, and each model name has a rank dot whose color and opacity match its chart segment. ## Structure - `app/index.html` is the source entrypoint for standalone, full, and inline use. Its JSON data block is the source of truth for the displayed models. - `app/config.js` contains non-sensitive runtime values such as the app title, version, optional Homepage origin, logo path, and Docs path. - `app/js/rank-logic.js` contains pure ranking and percentage logic. - `app/js/host-context-bootstrap.js` applies the optional pre-paint Homepage presentation snapshot before the first stylesheet. - `app/js/host-bridge.js` owns the current flat Homepage handshake and instance-scoped inline resize protocol. - `app/js/index.js` owns DOM rendering, the direct Preferences panel, links, host context updates, and smart-height requests. - `app/css/index.css` contains the compact standalone and embedded theme. - `app/assets/` contains the app mark and retained local SVG model assets. - `app/README.md` is the distribution-local support document. - `dist/` contains the Homepage-ready distribution generated from `app/`. - `requirements/` contains the accepted product decisions. - `test/` contains deterministic ranking and Homepage contract tests. ## Data and rendering The app reads the `models` array from the JSON block in `app/index.html`, removes entries with non-positive usage, preserves authored order, and shows the first three beside the chart. The chart compares only those visible values and normalizes them to 100%. Each model entry may contain: - `id`: a stable curated identifier - `name`: the display name - `image`: a relative path to retained local SVG metadata - `usage`: the chart-share value The visible rank dot and chart segment use the same accent color and rank opacity: 100% for rank one, 66% for rank two, and 33% for rank three. The local `image` fields remain curated metadata and are not rendered by the compact legend. Each chart segment is linked to its legend item. Hovering or keyboard-focusing one model makes that model fully opaque and makes every other model 33% more transparent by retaining 67% of its existing rendered opacity over 100ms; leaving or blurring restores the default rank transparencies over 300ms. The SVG chart tooltip is empty otherwise and shows the active model's percentage followed by its name. ## Homepage integration The published `dist/` directory is the Homepage runtime boundary. Homepage discovers the App from `dist/manifest.json`; it does not consume the source folder or the canonical Workspace README. The App supports: - standalone distribution testing through `app/index.html` or `dist/index.html`; - the Homepage direct route, which is a Homepage-managed full-surface frame; - authored `?embed=full` frames; - authored `?embed=inline` frames with content-based smart height. Hosted messages are flat `homepage/app/...` objects. The App accepts only messages from its exact parent frame and current origin, with the expected `models` slug. Config messages require the current `inline` or `full` mode, an opaque non-empty `instanceId`, and object-valued `config` and `preferences` fields. Matching config and `homepage/app/host-ready` messages produce one `homepage/app/ready` message for that exact instance. Replayed snapshots are idempotent, and a page reload or disposal resets the instance handshake. Inline resize requests contain a positive finite content height and the exact active `instanceId`. Homepage may clamp that request to its current 360px–560px smart-height range; an authored inline height remains host-owned. Homepage presentation context uses the currently displayed `theme`, `brightness`, `brightnessPreference`, `accent`, `accentText`, `onAccent`, `onAccentColor`, and allowlisted `cssVars` values. The App does not use target accent fields and does not declare or depend on the current generic host-only fields `reducedMotion`, `textScale`, or `devMode`. Embedded HTML keeps its background transparent so Homepage remains responsible for the surrounding surface. `homepageOrigin` in `app/config.js` is intentionally empty by default. Hosted frames fall back to their current origin; set the value only when a standalone direct shell needs an explicit Homepage origin. The direct logo and Docs links use that origin when available and otherwise retain their relative fallback targets. The published support README is `README.md` inside the distribution, while Docs remains `/docs/apps`. The app-owned Preferences panel is a standalone maintenance/documentation surface. Models does not contribute hosted Homepage Preferences because it has no persistent user-facing setting. It also does not use an API, provider integration, browser storage, Toast bridge, API-status reporting, lifecycle controls, layout handling, or App-specific extensions. ## Inputs and outputs Inputs are curated JSON values and retained local SVG assets. Outputs are the share chart, accessible chart description, accent rank-dot legend, direct maintenance panel, and current-context presentation. The app does not call an external API and does not persist browser data. ## Owner password boundary The Owner password is a Workspace-operations credential. It is not an app login, is not embedded in the app or distribution, and is not stored in browser storage. Updating the dashboard source remains a Workspace maintenance action. ## Local execution Serve the `app/` directory with any static file server and open `index.html`. For example: ```text python3 -m http.server 4173 --directory work/apps/models/app ``` Open the standalone entry URL for direct mode. Add `?embed=full` or `?embed=inline` to inspect hosted presentation modes. Homepage route and Embed validation must be performed in the active Homepage host; this App workspace does not edit Homepage host files. ## Known limitations - The included model names, usage values, colors, and symbols are starter values and should be replaced with the Owner's curated values. - The app intentionally does not provide in-browser editing or secure authentication. - Host-side serving, generation, registry discovery, route behavior, and host-rendered support links require validation in Homepage Builder.