From b54bec978f5968f866aded1d1ccfe9e6fc698e49 Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 09:57:09 -0500 Subject: [PATCH 1/7] docs: align sleepKIT home with KIT sites --- HANDOFF.md | 22 ++- astro-site/astro.config.mjs | 1 + astro-site/src/components/HomeHero.astro | 13 +- astro-site/src/content/docs/index.mdx | 183 ++++++----------------- astro-site/src/styles/site.css | 28 +++- 5 files changed, 93 insertions(+), 154 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 1256f95..a3eaa31 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,9 +1,21 @@ -# Canonical Astro documentation +# Home-page consistency handoff -Goal: retire the MkDocs compatibility layer while preserving public content and routes. +Goal: align sleepKIT with the KIT documentation sites and physioKIT. -PR: https://github.com/AmbiqAI/sleepkit/pull/49. Authored Markdown/MDX, navigation, redirects and static assets now belong to Astro. API pages, notebooks and downloads remain generated. MkDocs configuration and unused dependencies are removed. +State: +- Done locally in `codex/kit-home-consistency`: replace the hero dot with the existing product icon, render the links below the hero with the shared helia-ui Button, and set `header.titleRegularPrefix` so the prefix is regular and KIT stays bold. The home body follows the shared order: overview, four task cards with small pink icons, a short uv installation path, and four shared navigation cards. Detailed mode, dataset and model material lives on dedicated pages; legacy home anchors remain. +- Verified: Astro check and build pass. Output contract and route checks pass. All 17 Playwright tests pass on rerun; the first run had a transient Plotly iframe timeout, and the focused test passed independently. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. The shared navigation cards respond to body clicks and keyboard focus. +- Preview: http://127.0.0.1:8776/sleepkit/ +- Tracked by AmbiqAI/sleepkit#55. The site PR is pending; no release or deployment has occurred. -Review: notebook source links, download command examples and generation regression coverage corrected. Local build, type checks, content checks and browser tests pass. Independent final review and CI on the fix commit gate merging. CompressionKIT follows this cleanup. +Decisions: +- Reuse the repository's existing product icon and keep its current hero color and destination links. +- Use the shared Button component for the links under the hero; do not introduce a site-specific pill design. +- The header option is implemented in the local helia-ui worktree `/Users/adam.page/Ambiq/helia/helia-ui-header-prefix` but is not released. Preview dependencies have a local, untracked copy of that implementation. The consumer package pin stays at its current immutable version until a new helia-ui tag exists. -Ownership: edit astro-site/src/content/docs for authored pages, src/navigation.mjs for navigation and notebooks/ for notebook sources. See astro-site/README.md for generated paths and validation commands. +Next: +1. Open a draft site PR linked to issue #55 and request review. +2. After helia-ui#193 is merged and released, pin its immutable tag, regenerate the lockfile, rebuild, and review both themes. +3. Resolve review and CI findings, then ask Adam for approval. Do not merge without that approval. + +Gotcha: `npm ci` resets the preview-only helia-ui copy in `node_modules`; restore or use the released tag before rebuilding. diff --git a/astro-site/astro.config.mjs b/astro-site/astro.config.mjs index 7c9f81f..778d431 100644 --- a/astro-site/astro.config.mjs +++ b/astro-site/astro.config.mjs @@ -64,6 +64,7 @@ export default defineConfig({ sidebar: "always", header: { title: "sleepKIT", + titleRegularPrefix: "sleep", hub: { label: "HELIA", href: "https://ambiqai.github.io/helia-developer-hub/", diff --git a/astro-site/src/components/HomeHero.astro b/astro-site/src/components/HomeHero.astro index 6c8817e..5eec666 100644 --- a/astro-site/src/components/HomeHero.astro +++ b/astro-site/src/components/HomeHero.astro @@ -1,6 +1,7 @@ --- import { readFileSync } from 'node:fs'; import DefaultHero from '@astrojs/starlight/components/Hero.astro'; +import Button from '@ambiqai/helia-ui/astro/Button'; const { data } = Astro.locals.starlightRoute.entry; const source = readFileSync('../pyproject.toml', 'utf8'); const version = source.match(/^version\s*=\s*"([^"]+)"/m)?.[1]; @@ -16,7 +17,7 @@ const capabilities = [ --- {data.hero?.tagline ? <>
-
sleepKITv{version}
+
sleepKITv{version}

From sleep signals
to Edge AI.

@@ -33,14 +34,14 @@ const capabilities = [
: } diff --git a/astro-site/src/content/docs/index.mdx b/astro-site/src/content/docs/index.mdx index 263d595..603be2d 100644 --- a/astro-site/src/content/docs/index.mdx +++ b/astro-site/src/content/docs/index.mdx @@ -5,165 +5,70 @@ hero: tagline: "sleepKIT is a Python development kit for building sleep-monitoring AI for Ambiq devices. Turn sensor recordings into features, train and evaluate models, and prepare them for deployment at the edge." --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { Icon as StarlightIcon } from '@astrojs/starlight/components'; +import Card from '@ambiqai/helia-ui/astro/Card'; +import CardHeader from '@ambiqai/helia-ui/astro/CardHeader'; +import CardContent from '@ambiqai/helia-ui/astro/CardContent'; +import CardGrid from '@ambiqai/helia-ui/astro/CardGrid'; +import Icon from '@ambiqai/helia-ui/astro/Icon'; -## A starting point for your sleep-monitoring application + -Building a sleep model takes more than choosing a network. You need recordings and labels, consistent signal processing, a training setup and a way to evaluate the results. sleepKIT brings these pieces together in a configurable development workflow for engineers and researchers working on wearable and edge applications. +## What is sleepKIT? -Start with the included dataset integrations, feature sets, model configurations and examples. Run experiments from the command line or compose a custom workflow with the Python API. You can replace individual components as your application develops, then use the export tools to prepare models for integration on Ambiq devices. +Building a sleep-monitoring model involves recordings and labels, signal processing, a training setup and a way to assess the result. sleepKIT brings those pieces into a configurable Python workflow for wearable and edge applications. + +Start with an included task, run it from the command line or adapt the workflow through the Python API. The task and guide pages explain the options in detail, including how to prepare a model for integration on Ambiq devices. ## Included tasks -Start with a built-in task, or extend the same workflow with your own training, evaluation and export routines. +Start with a built-in task, or extend the workflow with your own training, evaluation and export routines. -Code and Ambiq-authored documentation use BSD-3-Clause, except separately licensed material. Model weights and datasets have [their own terms](/sleepkit/model-licensing-policy/). - ## Installation -Use **uv** for a Python project, **uvx** to run the CLI in an isolated environment, or **pipx** to keep the CLI installed. Choose **Git clone** when developing sleepKIT itself. - -
+In a Python 3.12 project, add sleepKIT and check that the command line tool is available: - - - -Create a project with Python 3.12, then add sleepKIT. In an existing uv project, start with `uv add sleepkit`. - -```bash title="Terminal" +```bash uv init --python 3.12 my-sleep-project cd my-sleep-project uv add sleepkit uv run sleepkit --help ``` - - - -Run the CLI without adding sleepKIT to a project. The first invocation downloads sleepKIT and its dependencies into an isolated environment. - -```bash title="Terminal" -uvx --python 3.12 sleepkit --help -``` - -Use a project installation for Python imports and notebooks. - - - - -Install the CLI in its own environment. This command uses an installed Python 3.12 interpreter. - -```bash title="Terminal" -pipx install --python python3.12 sleepkit -sleepkit --help -``` - -If the command is not on your PATH, run `pipx ensurepath` and reopen your terminal. Use a project installation for Python imports and notebooks. +The [quickstart](/sleepkit/quickstart/) covers `pip` and source-checkout installation, configuration and your first workflow. - - - -Install into an activated virtual environment. - -```bash title="Terminal" -python -m pip install sleepkit -sleepkit --help -``` - - - - -Work with the repository source and its development dependencies. - -```bash title="Terminal" -git clone https://github.com/AmbiqAI/sleepkit.git -cd sleepkit -uv sync --python 3.12 -uv run sleepkit --help -``` - - - - -
- -Need the package manager first? See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) or [pipx installation guide](https://pipx.pypa.io/stable/installation/). The [Quickstart](/sleepkit/quickstart/) covers configuration and your first workflow. - ---- - -## Usage - -__sleepKIT__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, sleepKIT exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, sleepKIT can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](/sleepkit/quickstart/) to quickly get up and running in minutes. - ---- - -## Modes - -The __ADK__ provides a number of [modes](/sleepkit/modes/) that can be invoked for a given task. These modes can be accessed via the CLI or directly within the Python package. Each mode is accompanied by a set of [task parameters](/sleepkit/modes/configuration/) that can be customized to fit the user's needs. - -- **[Download](/sleepkit/modes/download/)**: Download specified datasets -- **[Feature](/sleepkit/features/)**: Generate features from datasets -- **[Train](/sleepkit/modes/train/)**: Train a model for specified task and feature set -- **[Evaluate](/sleepkit/modes/evaluate/)**: Evaluate a model for specified task and feature set -- **[Export](/sleepkit/modes/export/)**: Export a trained model to TensorFlow Lite and TFLM -- **[Demo](/sleepkit/modes/demo/)**: Run task-level demo on PC or remotely on Ambiq EVB - ---- - -## Datasets - -__sleepKIT__ includes several open-source datasets via the __dataset factory__. Each dataset has a corresponding Python class to aid in downloading and extracting the data. The datasets are used to generate feature sets that are then used to train and evaluate the models. Check out the [Datasets Guide](/sleepkit/datasets/) to learn more about the available datasets along with their corresponding licenses and limitations. - -* **[MESA](/sleepkit/datasets/mesa/)**: A longitudinal investigation of factors associated with the development of subclinical cardiovascular disease and the progression of subclinical to clinical cardiovascular disease in 6,814 black, white, Hispanic, and Chinese -* **[CMIDSS](/sleepkit/datasets/cmidss/)**: The Child Mind Institute - Detect Sleep States (CMIDSS) dataset comprises 300 subjects with over 500 multi-day recordings of wrist-worn accelerometer data annotated with two event types: onset, the beginning of sleep, and wakeup, the end of sleep. -* **[YSYW](/sleepkit/datasets/ysyw/)**: A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational Clinical Neurophysiology Laboratory, and the Clinical Data Ani- mation Center. -* **[STAGES](/sleepkit/datasets/stages/)**: The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites from six centers including Stanford University, Bogan Sleep Consulting, Geisinger Health, Mayo Clinic, MedSleep, and St. Luke's Hospital. - ---- - -## Models - -The __ADK__ provides a variety of model architectures geared towards efficient, real-time edge applications. These models are provided by Ambiq's [helia-edge](https://ambiqai.github.io/helia-edge/) and expose a set of parameters that can be used to fully customize the network for a given application. In addition, sleepKIT includes a model factory, [ModelFactory](/sleepkit/models/#model-factory), to register current models as well as allow new custom architectures to be added. Check out the [Models Guide](/sleepkit/models/) to learn more about the available network architectures and model factory. - ---- - -## Features - -The __ADK__ provides a __feature store__ that allows you to easily create and extract features from the given datasets. The feature store includes a number of feature sets used to train the included model zoo. Each feature set exposes a number of high-level parameters that can be used to customize the feature extraction process for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package. Check out the [Features Guide](/sleepkit/features/) to learn more about the available feature set generators. - ---- - -## Model Zoo - -A number of pre-trained models are available for each task. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __sleepKIT__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily recreate the models or use them as a starting point for custom solutions. Furthermore, the performance metrics provide insights into the model's accuracy, precision, recall, and F1 score. For a number of the models, we provide experimental and ablation studies to showcase the impact of various design choices. Check out the [Model Zoo](/sleepkit/zoo/) to learn more about the available models and their corresponding performance metrics. - ---- +Code and Ambiq-authored documentation use BSD-3-Clause, except separately licensed material. Model weights and datasets have [their own terms](/sleepkit/model-licensing-policy/). -## [Guides](/sleepkit/guides/) + -Checkout the [Guides](/sleepkit/guides/) to see detailed examples and tutorials on how to use sleepKIT for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the capabilities provided by sleepKIT. +## Explore the documentation ---- + +

Install sleepKIT and run a first workflow.

Start here →

+

Choose a sleep-monitoring task or bring your own.

Explore tasks →

+

Follow examples for training, evaluation and export.

Follow a guide →

+

Look up packages, classes and function parameters.

Browse the API →

+
diff --git a/astro-site/src/styles/site.css b/astro-site/src/styles/site.css index 41c54ad..563864f 100644 --- a/astro-site/src/styles/site.css +++ b/astro-site/src/styles/site.css @@ -102,12 +102,34 @@ margin: 0; padding: 1.25rem; border: 1px solid var(--sl-color-gray-5); - border-top: 3px solid var(--sleepkit-button-border); border-radius: 0.75rem; color: var(--sl-color-text); text-decoration: none; } -.sleepkit-task-card strong { +.sleepkit-card-heading { + display: inline-flex; + align-items: center; + gap: 0.6rem; +} +.sleepkit-card-heading svg { + flex: none; + color: var(--sleepkit-button-text); + font-size: 1.15rem; +} +.sl-markdown-content .helia-card-header .helia-icon__glyph { + color: var(--sleepkit-button-text); +} +.sl-markdown-content .sleepkit-card-cue { + color: var(--sleepkit-button-text); + font-weight: 600; + margin-top: auto; +} +.sl-markdown-content .kit-home-nav .helia-card-content { + display: flex; + flex: 1; + flex-direction: column; +} +.sleepkit-card-heading strong { font-size: 1.1rem; color: var(--sl-color-white); } @@ -123,7 +145,7 @@ .sleepkit-task-card:hover { background: var(--sl-color-gray-6); } -@media (max-width: 50rem) { +@media (max-width: 40rem) { .sleepkit-task-grid { grid-template-columns: 1fr; } From 22b5fa6befbb47117458c61479bae8761eb6dead Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 10:03:27 -0500 Subject: [PATCH 2/7] test: follow installation tabs on quickstart --- HANDOFF.md | 2 +- astro-site/tests/mobile-sections.spec.ts | 2 +- astro-site/tests/site.spec.ts | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index a3eaa31..c8bf045 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -4,7 +4,7 @@ Goal: align sleepKIT with the KIT documentation sites and physioKIT. State: - Done locally in `codex/kit-home-consistency`: replace the hero dot with the existing product icon, render the links below the hero with the shared helia-ui Button, and set `header.titleRegularPrefix` so the prefix is regular and KIT stays bold. The home body follows the shared order: overview, four task cards with small pink icons, a short uv installation path, and four shared navigation cards. Detailed mode, dataset and model material lives on dedicated pages; legacy home anchors remain. -- Verified: Astro check and build pass. Output contract and route checks pass. All 17 Playwright tests pass on rerun; the first run had a transient Plotly iframe timeout, and the focused test passed independently. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. The shared navigation cards respond to body clicks and keyboard focus. +- Verified: Astro check and build pass. Output contract and route checks pass. All 17 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. The shared navigation cards respond to body clicks and keyboard focus. - Preview: http://127.0.0.1:8776/sleepkit/ - Tracked by AmbiqAI/sleepkit#55. The site PR is pending; no release or deployment has occurred. diff --git a/astro-site/tests/mobile-sections.spec.ts b/astro-site/tests/mobile-sections.spec.ts index 7f19d3e..474acd5 100644 --- a/astro-site/tests/mobile-sections.spec.ts +++ b/astro-site/tests/mobile-sections.spec.ts @@ -47,7 +47,7 @@ for (const colorScheme of ['light', 'dark'] as const) { test(`tabbed terminals keep commands and copy controls in ${colorScheme}`, async ({ page }) => { await page.setViewportSize({ width: 835, height: 890 }); await page.emulateMedia({ colorScheme }); - await page.goto(`${base}/`); + await page.goto(`${base}/quickstart/`); const terminal = page.locator('[role="tabpanel"] .frame.is-terminal:visible').first(); await expect(terminal).toBeVisible(); await expect(terminal.locator('.header')).toBeHidden(); diff --git a/astro-site/tests/site.spec.ts b/astro-site/tests/site.spec.ts index 4663490..5d81d0c 100644 --- a/astro-site/tests/site.spec.ts +++ b/astro-site/tests/site.spec.ts @@ -148,6 +148,7 @@ test("navigation scopes historical routes and installation contains only command await page.goto(""); await expect(page.locator('nav[aria-label="Primary"] a')).toHaveCount(5); await expect(page.locator("helia-ascii-terminal")).toHaveCount(0); + await page.goto("quickstart/"); await page.getByRole("tab", { name: "Git clone", exact: true }).click(); const content = page.getByRole("tabpanel").filter({ hasText: "git clone" }); await expect(content).toBeVisible(); From 97adb52bd5e315247383550d553f57c6e25f72ea Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 10:15:04 -0500 Subject: [PATCH 3/7] fix: retain shared landing button styles --- HANDOFF.md | 6 ++--- astro-site/src/components/HomeHero.astro | 4 ++-- astro-site/tests/landing.spec.ts | 29 ++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 5 deletions(-) create mode 100644 astro-site/tests/landing.spec.ts diff --git a/HANDOFF.md b/HANDOFF.md index c8bf045..63e2abc 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -4,9 +4,9 @@ Goal: align sleepKIT with the KIT documentation sites and physioKIT. State: - Done locally in `codex/kit-home-consistency`: replace the hero dot with the existing product icon, render the links below the hero with the shared helia-ui Button, and set `header.titleRegularPrefix` so the prefix is regular and KIT stays bold. The home body follows the shared order: overview, four task cards with small pink icons, a short uv installation path, and four shared navigation cards. Detailed mode, dataset and model material lives on dedicated pages; legacy home anchors remain. -- Verified: Astro check and build pass. Output contract and route checks pass. All 17 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. The shared navigation cards respond to body clicks and keyboard focus. +- Verified: Astro check and build pass. Output contract and route checks pass. All 19 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. Browser regression checks verify readable shared quick buttons in both themes and navigation from card-body clicks. - Preview: http://127.0.0.1:8776/sleepkit/ -- Tracked by AmbiqAI/sleepkit#55. The site PR is pending; no release or deployment has occurred. +- Tracked by AmbiqAI/sleepkit#55. Draft PR #56 is open; no release or deployment has occurred. Decisions: - Reuse the repository's existing product icon and keep its current hero color and destination links. @@ -14,7 +14,7 @@ Decisions: - The header option is implemented in the local helia-ui worktree `/Users/adam.page/Ambiq/helia/helia-ui-header-prefix` but is not released. Preview dependencies have a local, untracked copy of that implementation. The consumer package pin stays at its current immutable version until a new helia-ui tag exists. Next: -1. Open a draft site PR linked to issue #55 and request review. +1. Review draft site PR #56, linked to issue #55 and request review. 2. After helia-ui#193 is merged and released, pin its immutable tag, regenerate the lockfile, rebuild, and review both themes. 3. Resolve review and CI findings, then ask Adam for approval. Do not merge without that approval. diff --git a/astro-site/src/components/HomeHero.astro b/astro-site/src/components/HomeHero.astro index 5eec666..b6b96ee 100644 --- a/astro-site/src/components/HomeHero.astro +++ b/astro-site/src/components/HomeHero.astro @@ -49,11 +49,11 @@ const capabilities = [ .hero-copy p { max-width: 57ch; font-size: 1.08rem; line-height: 1.75; } nav { display: flex; flex-wrap: wrap; gap: .75rem; } .hero-actions { margin-top: 2rem; } - nav a { display: inline-flex; align-items: center; gap: .75rem; padding: .7rem 1.15rem; border: 1px solid #505761; border-radius: 999px; color: #f3f4f7; text-decoration: none; font-weight: 600; } + .hero-actions a { display: inline-flex; align-items: center; gap: .75rem; padding: .7rem 1.15rem; border: 1px solid #505761; border-radius: 999px; color: #f3f4f7; text-decoration: none; font-weight: 600; } .hero-actions .primary { color: #151219; background: #f77aaa; border-color: #f77aaa; } .hero-actions a:hover { border-color: #ffafd0; background: #28212b; } .hero-actions .primary:hover { color: #151219; background: #ffafd0; } - a:focus-visible { outline: 2px solid #f77aaa; outline-offset: 4px; } + .hero-actions a:focus-visible { outline: 2px solid #f77aaa; outline-offset: 4px; } .capabilities { background: #191e25; border: 1px solid #343d49; border-radius: 1.15rem; padding: 1.35rem; } .capabilities-label { color: #c1c7d1; text-transform: uppercase; letter-spacing: .1em; font-size: .72rem; font-weight: 600; margin: 0 0 1.15rem; } ol { display: grid; gap: .65rem; list-style: none; margin: 0; padding: 0; } diff --git a/astro-site/tests/landing.spec.ts b/astro-site/tests/landing.spec.ts new file mode 100644 index 0000000..4da9cae --- /dev/null +++ b/astro-site/tests/landing.spec.ts @@ -0,0 +1,29 @@ +import { expect, test } from '@playwright/test'; + +for (const theme of ['light', 'dark'] as const) { + test(`landing buttons remain readable and cards navigate in ${theme}`, async ({ page }) => { + await page.setViewportSize({ width: 390, height: 900 }); + await page.goto('/sleepkit/'); + await page.evaluate(value => document.documentElement.dataset.theme = value, theme); + const button = page.locator('.task-links a').first(); + await expect(button).toBeVisible(); + const colors = await button.evaluate(node => { + const probe = document.createElement('span'); + probe.style.color = 'var(--helia-ink-primary)'; + document.body.append(probe); + const expected = getComputedStyle(probe).color; + probe.remove(); + return { actual: getComputedStyle(node).color, expected }; + }); + await expect(button).toHaveCSS('color', colors.expected); + expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true); + const card = page.locator('.kit-home-nav .helia-card').first(); + const destination = await card.locator('a').first().getAttribute('href'); + const description = card.locator('.helia-card-content p').first(); + await description.scrollIntoViewIfNeeded(); + const body = await description.boundingBox(); + expect(body).not.toBeNull(); + await page.mouse.click(body!.x + body!.width / 2, body!.y + body!.height / 2); + await expect(page).toHaveURL(new URL(destination!, page.url()).href); + }); +} From edf636784f40d37d96c61cf968a468065ce92f91 Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 10:25:08 -0500 Subject: [PATCH 4/7] docs: record published review fixes and release gate --- HANDOFF.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/HANDOFF.md b/HANDOFF.md index 63e2abc..1d775ac 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -19,3 +19,5 @@ Next: 3. Resolve review and CI findings, then ask Adam for approval. Do not merge without that approval. Gotcha: `npm ci` resets the preview-only helia-ui copy in `node_modules`; restore or use the released tag before rebuilding. + +Publication: final review fixes are pushed. Fresh CI and Copilot re-reviews requested; verify the final head before approval. Product PRs remain draft pending shared helia-ui approval, release and immutable dependency pins. From 59cc533e05c3973ebc6f5e2f7b2fa3bcece2da2a Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 10:36:12 -0500 Subject: [PATCH 5/7] fix: preserve not-found page outside the home route --- HANDOFF.md | 2 ++ astro-site/src/components/HomeHero.astro | 3 ++- astro-site/tests/landing.spec.ts | 7 +++++++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/HANDOFF.md b/HANDOFF.md index 1d775ac..395b089 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -21,3 +21,5 @@ Next: Gotcha: `npm ci` resets the preview-only helia-ui copy in `node_modules`; restore or use the released tag before rebuilding. Publication: final review fixes are pushed. Fresh CI and Copilot re-reviews requested; verify the final head before approval. Product PRs remain draft pending shared helia-ui approval, release and immutable dependency pins. + +Not-found handling: restrict the product hero to the home route so unknown routes show the 404 page; built output and browser checks cover the fallback. diff --git a/astro-site/src/components/HomeHero.astro b/astro-site/src/components/HomeHero.astro index b6b96ee..212f352 100644 --- a/astro-site/src/components/HomeHero.astro +++ b/astro-site/src/components/HomeHero.astro @@ -7,6 +7,7 @@ const source = readFileSync('../pyproject.toml', 'utf8'); const version = source.match(/^version\s*=\s*"([^"]+)"/m)?.[1]; if (!version) throw new Error('Missing sleepKIT version in pyproject.toml'); const base = import.meta.env.BASE_URL; +const isHome = Astro.url.pathname.replace(/\/+$/, '') === base.replace(/\/+$/, ''); const tasks = [['Sleep detection', 'detect'], ['Sleep staging', 'stage'], ['Sleep apnea', 'apnea']]; const capabilities = [ ['01', 'Prepare signals', 'Dataset loaders and feature extraction'], @@ -15,7 +16,7 @@ const capabilities = [ ['04', 'Prepare for the edge', 'Model export and task-level demos'], ]; --- -{data.hero?.tagline ? <> +{isHome && data.hero?.tagline ? <>
sleepKITv{version}
diff --git a/astro-site/tests/landing.spec.ts b/astro-site/tests/landing.spec.ts index 4da9cae..8220126 100644 --- a/astro-site/tests/landing.spec.ts +++ b/astro-site/tests/landing.spec.ts @@ -27,3 +27,10 @@ for (const theme of ['light', 'dark'] as const) { await expect(page).toHaveURL(new URL(destination!, page.url()).href); }); } + + +test('unknown routes show the not-found page rather than the home hero', async ({ page }) => { + const response = await page.goto('/sleepkit/this-route-does-not-exist/'); + expect(response?.status()).toBe(404); + await expect(page.getByRole('heading', { name: '404', exact: true })).toBeVisible(); +}); From a8c57e0d5af277a5ed98d66b0929f6d5adc015b3 Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 11:02:16 -0500 Subject: [PATCH 6/7] docs: pin released shared header and verify KIT styling --- HANDOFF.md | 14 +++++--------- astro-site/package-lock.json | 26 +++----------------------- astro-site/package.json | 2 +- astro-site/tests/landing.spec.ts | 9 +++++++++ 4 files changed, 18 insertions(+), 33 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 395b089..e2ff324 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -4,22 +4,18 @@ Goal: align sleepKIT with the KIT documentation sites and physioKIT. State: - Done locally in `codex/kit-home-consistency`: replace the hero dot with the existing product icon, render the links below the hero with the shared helia-ui Button, and set `header.titleRegularPrefix` so the prefix is regular and KIT stays bold. The home body follows the shared order: overview, four task cards with small pink icons, a short uv installation path, and four shared navigation cards. Detailed mode, dataset and model material lives on dedicated pages; legacy home anchors remain. -- Verified: Astro check and build pass. Output contract and route checks pass. All 19 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. Browser regression checks verify readable shared quick buttons in both themes and navigation from card-body clicks. +- Verified: Astro check and build pass. Output contract and route checks pass. All 20 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. Browser regression checks verify readable shared quick buttons in both themes and navigation from card-body clicks. - Preview: http://127.0.0.1:8776/sleepkit/ - Tracked by AmbiqAI/sleepkit#55. Draft PR #56 is open; no release or deployment has occurred. Decisions: - Reuse the repository's existing product icon and keep its current hero color and destination links. - Use the shared Button component for the links under the hero; do not introduce a site-specific pill design. -- The header option is implemented in the local helia-ui worktree `/Users/adam.page/Ambiq/helia/helia-ui-header-prefix` but is not released. Preview dependencies have a local, untracked copy of that implementation. The consumer package pin stays at its current immutable version until a new helia-ui tag exists. +- Pin helia-ui v0.1.0-alpha.24, published from f7158bf, with an npm 11.19.0 lockfile. Clean installs reproduce the shared header without a local patch. -Next: -1. Review draft site PR #56, linked to issue #55 and request review. -2. After helia-ui#193 is merged and released, pin its immutable tag, regenerate the lockfile, rebuild, and review both themes. -3. Resolve review and CI findings, then ask Adam for approval. Do not merge without that approval. +Next: finish checks against the released package, final review and CI, merge under Adam's authorization, then verify the Pages deployment. -Gotcha: `npm ci` resets the preview-only helia-ui copy in `node_modules`; restore or use the released tag before rebuilding. +Not-found handling: restrict the product hero to the home route so unknown routes show the 404 page; built output and browser checks cover the fallback. -Publication: final review fixes are pushed. Fresh CI and Copilot re-reviews requested; verify the final head before approval. Product PRs remain draft pending shared helia-ui approval, release and immutable dependency pins. -Not-found handling: restrict the product hero to the home route so unknown routes show the 404 page; built output and browser checks cover the fallback. +Release validation: clean installation of alpha.24 passed. Final check/build/output checks pass, with 20 rendered acceptance checks passing against the clean released dependency. User authorized merging after green CI. diff --git a/astro-site/package-lock.json b/astro-site/package-lock.json index 9a56fa2..60ff6b8 100644 --- a/astro-site/package-lock.json +++ b/astro-site/package-lock.json @@ -8,7 +8,7 @@ "name": "sleepkit-site", "version": "0.0.0", "dependencies": { - "@ambiqai/helia-ui": "github:AmbiqAI/helia-ui#v0.1.0-alpha.23", + "@ambiqai/helia-ui": "github:AmbiqAI/helia-ui#v0.1.0-alpha.24", "@astrojs/markdown-remark": "^7.3.1", "@astrojs/react": "7.0.0", "@astrojs/starlight": "^0.41.5", @@ -35,8 +35,8 @@ } }, "node_modules/@ambiqai/helia-ui": { - "version": "0.1.0-alpha.23", - "resolved": "git+ssh://git@github.com/AmbiqAI/helia-ui.git#f523f6008aca7e1f9b4c3a17198f3f48da83cd7a", + "version": "0.1.0-alpha.24", + "resolved": "git+ssh://git@github.com/AmbiqAI/helia-ui.git#f7158bf0f5f6014371bfc3ac7c28e8c6709d5829", "license": "BSD-3-Clause", "dependencies": { "@fontsource-variable/roboto": "5.3.0", @@ -427,7 +427,6 @@ "resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-7.3.1.tgz", "integrity": "sha512-QCjsjZQl0+Cgb91+T3Ip9hyUe1r5aLm4udi584rML9YO3syupbAYE+jWpAxYg+z4lFLNUugPrylFxZ+8qFTClg==", "license": "MIT", - "peer": true, "dependencies": { "@astrojs/internal-helpers": "0.11.0", "@astrojs/prism": "4.0.2", @@ -787,7 +786,6 @@ "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.41.11.tgz", "integrity": "sha512-hM95Mbsl4l60SBwaNQA/HTxpOLGfeB5EfR9qY3kr0SsAVKUspCssjO0RVBsLiPAE6EA5xuORcCoz/Q6DTX+MuQ==", "license": "MIT", - "peer": true, "dependencies": { "@astrojs/markdown-satteri": "^0.3.5", "@astrojs/mdx": "^7.0.5", @@ -1182,7 +1180,6 @@ "integrity": "sha512-zLpS5asjEb7lq8jYLq37N6XKaE41DIexlY1rF/z4/tIl3wo13Sqm28fRyfIsKZD+NZ8mM5RoKkpW/rBcuoSZSg==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "@emnapi/wasi-threads": "1.2.3", "tslib": "^2.4.0" @@ -1194,7 +1191,6 @@ "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "tslib": "^2.4.0" } @@ -3166,7 +3162,6 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz", "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==", "license": "MIT", - "peer": true, "dependencies": { "csstype": "^3.2.2" } @@ -3176,7 +3171,6 @@ "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz", "integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==", "license": "MIT", - "peer": true, "peerDependencies": { "@types/react": "^19.3.0" } @@ -3358,7 +3352,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz", "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -3381,7 +3374,6 @@ "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -3526,7 +3518,6 @@ "resolved": "https://registry.npmjs.org/astro/-/astro-7.3.3.tgz", "integrity": "sha512-NF08hk3edFkVmr9avf9HW/rQyf6NrpbVDyYj2cVN3JfijDhfJYh1ivWVTY5PUd5+rRZn/Vtu4iaeyNlP0Iv6mg==", "license": "MIT", - "peer": true, "dependencies": { "@astrojs/compiler-rs": "^0.4.0", "@astrojs/internal-helpers": "0.11.0", @@ -4217,7 +4208,6 @@ "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.34.3.tgz", "integrity": "sha512-yfYGhRcGAntq6YBD583j4n0Eg3jIxvWmZtz/5uz9UYkeIStSlMxuUja+ec5j3iBD8nv1rwaOAYMW09tBdkSeaQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10" } @@ -4618,7 +4608,6 @@ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", "license": "ISC", - "peer": true, "engines": { "node": ">=12" } @@ -5006,7 +4995,6 @@ "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", "hasInstallScript": true, "license": "MIT", - "peer": true, "bin": { "esbuild": "bin/esbuild" }, @@ -8013,7 +8001,6 @@ "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "playwright-core": "1.63.0" }, @@ -8072,7 +8059,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.18", "picocolors": "^1.1.1", @@ -8126,7 +8112,6 @@ "integrity": "sha512-Z/CJHIkdujO/OtN7nXUii0Rf3VT5SRuhjBA82Xvu2XhBUgX3nhP67T0LHceBdQLex7OOFGTox+Q5Yg8Jk2Qivg==", "dev": true, "license": "MIT", - "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -8176,7 +8161,6 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.3.0.tgz", "integrity": "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -8186,7 +8170,6 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.0.tgz", "integrity": "sha512-JDk8dgif51OjFoDE70+OT9ICyYr+69HlmihNwp1+Nsfbna3t5sIiCa9ZJktDmQ4/1b/rn26hIAR2uYXDMr5r0Q==", "license": "MIT", - "peer": true, "dependencies": { "scheduler": "^0.28.0" }, @@ -9206,7 +9189,6 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -9644,7 +9626,6 @@ "resolved": "https://registry.npmjs.org/vite/-/vite-8.3.1.tgz", "integrity": "sha512-/bvH9E9tmCXRGp2uXY3WbOldqpTwFkbha/8ANaEQ6VkxhH60KyqLwgZq6lG2y+4uT55x9+9eUHMpQ7uGnOCKjA==", "license": "MIT", - "peer": true, "dependencies": { "lightningcss": "^1.33.0", "picomatch": "^4.0.7", @@ -10087,7 +10068,6 @@ "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==", "devOptional": true, "license": "ISC", - "peer": true, "bin": { "yaml": "bin.mjs" }, diff --git a/astro-site/package.json b/astro-site/package.json index 473fcb0..a5199c8 100644 --- a/astro-site/package.json +++ b/astro-site/package.json @@ -21,7 +21,7 @@ "test": "playwright test" }, "dependencies": { - "@ambiqai/helia-ui": "github:AmbiqAI/helia-ui#v0.1.0-alpha.23", + "@ambiqai/helia-ui": "github:AmbiqAI/helia-ui#v0.1.0-alpha.24", "@astrojs/markdown-remark": "^7.3.1", "@astrojs/react": "7.0.0", "@astrojs/starlight": "^0.41.5", diff --git a/astro-site/tests/landing.spec.ts b/astro-site/tests/landing.spec.ts index 8220126..a3c4020 100644 --- a/astro-site/tests/landing.spec.ts +++ b/astro-site/tests/landing.spec.ts @@ -4,6 +4,15 @@ for (const theme of ['light', 'dark'] as const) { test(`landing buttons remain readable and cards navigate in ${theme}`, async ({ page }) => { await page.setViewportSize({ width: 390, height: 900 }); await page.goto('/sleepkit/'); + const title = page.locator('.helia-site-header__title'); + const prefix = title.locator('.helia-site-header__prefix'); + await expect(prefix).toHaveText('sleep'); + const weights = await title.evaluate(node => ({ + full: Number(getComputedStyle(node).fontWeight), + prefix: Number(getComputedStyle(node.querySelector('.helia-site-header__prefix')!).fontWeight), + })); + expect(weights.prefix).toBeLessThan(weights.full); + await expect(page.locator('.hero-meta img')).toBeVisible(); await page.evaluate(value => document.documentElement.dataset.theme = value, theme); const button = page.locator('.task-links a').first(); await expect(button).toBeVisible(); From 7361ab93670fcad2a52aa7aa00e17baa95316dfb Mon Sep 17 00:00:00 2001 From: Adam Page Date: Wed, 7 Oct 2026 11:08:01 -0500 Subject: [PATCH 7/7] test: assert the sleepKIT hero is absent on unknown routes --- HANDOFF.md | 22 +++++++--------------- astro-site/tests/landing.spec.ts | 1 + 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index e2ff324..63f9031 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,21 +1,13 @@ -# Home-page consistency handoff +# sleepKIT landing consistency -Goal: align sleepKIT with the KIT documentation sites and physioKIT. +Goal: issue #55, align the landing page with heartKIT, compressionKIT and physioKIT. PR #56 is ready for review on codex/kit-home-consistency. Adam authorized merge after green CI. -State: -- Done locally in `codex/kit-home-consistency`: replace the hero dot with the existing product icon, render the links below the hero with the shared helia-ui Button, and set `header.titleRegularPrefix` so the prefix is regular and KIT stays bold. The home body follows the shared order: overview, four task cards with small pink icons, a short uv installation path, and four shared navigation cards. Detailed mode, dataset and model material lives on dedicated pages; legacy home anchors remain. -- Verified: Astro check and build pass. Output contract and route checks pass. All 20 Playwright tests pass. The first PR CI run exposed three tests that still searched the shortened home page for the old installation tabs. They now test the Quickstart page, where those tabs remain. Desktop, 785px and 390px views were inspected in light and dark mode, with no horizontal overflow. Browser regression checks verify readable shared quick buttons in both themes and navigation from card-body clicks. -- Preview: http://127.0.0.1:8776/sleepkit/ -- Tracked by AmbiqAI/sleepkit#55. Draft PR #56 is open; no release or deployment has occurred. +Done: product hero icon, regular sleep prefix and bold KIT navbar suffix, shared quick buttons, overview, task cards with small pink icons and neutral borders, short installation path and full-card documentation links. Historical home anchors remain. The custom hero only renders on the home route. -Decisions: -- Reuse the repository's existing product icon and keep its current hero color and destination links. -- Use the shared Button component for the links under the hero; do not introduce a site-specific pill design. -- Pin helia-ui v0.1.0-alpha.24, published from f7158bf, with an npm 11.19.0 lockfile. Clean installs reproduce the shared header without a local patch. +Verified: immutable helia-ui v0.1.0-alpha.24 pin and npm 11.19.0 lockfile, clean install, Astro check/build/output and 20 browser tests. Light/dark mobile and desktop screenshots inspected. Tests exercise title weights, logo, readable buttons, card-body navigation and absent home hero on 404. Full PR CI passed before the final regression assertion; CI on this assertion must finish before merge. -Next: finish checks against the released package, final review and CI, merge under Adam's authorization, then verify the Pages deployment. +Review: prior dependency and installation-test findings resolved. Final review requested a more explicit 404 assertion and consistent handoff status; both addressed. -Not-found handling: restrict the product hero to the home route so unknown routes show the 404 page; built output and browser checks cover the fallback. +Next: verify final CI, complete review, squash merge and confirm Pages deployment. No publication of this landing change is claimed yet. - -Release validation: clean installation of alpha.24 passed. Final check/build/output checks pass, with 20 rendered acceptance checks passing against the clean released dependency. User authorized merging after green CI. +Preview: http://127.0.0.1:8776/sleepkit/. Builds use generated API and notebook material; training is not run. A clean install needs no package patch. diff --git a/astro-site/tests/landing.spec.ts b/astro-site/tests/landing.spec.ts index a3c4020..4bd0cf3 100644 --- a/astro-site/tests/landing.spec.ts +++ b/astro-site/tests/landing.spec.ts @@ -42,4 +42,5 @@ test('unknown routes show the not-found page rather than the home hero', async ( const response = await page.goto('/sleepkit/this-route-does-not-exist/'); expect(response?.status()).toBe(404); await expect(page.getByRole('heading', { name: '404', exact: true })).toBeVisible(); + await expect(page.locator('.sleepkit-hero')).toHaveCount(0); });