@terreno/mcp 57.7.0 → 57.8.0

package/dist/docs/versioned/next/reference/announcements.md

@@ -27,6 +27,7 @@ new TerrenoApp({ userModel: User })
 | `help.enabled` | `boolean` | `false` | Registers help search/detail routes for MCP and in-app help |
 | `matchAudience` | `(user, announcement) => boolean` | always `true` | Opaque audience JSON filter composed with `audienceType` via `matchAudienceByType` |
 | `isStaff` | `(user) => boolean` | `user.admin === true` | Staff check used by `matchAudienceByType` for `audienceType` |
+| `uploadToken` | `string` | unset | Dedicated bearer token for idempotent `POST /announcements/import-release` automation |
 | `permissions` | partial CRUD overrides | admin-only | Overrides default `IsAdmin` permissions on announcement CRUD |
 
 ## Acknowledgement policy
@@ -52,7 +53,7 @@ Legacy MongoDB documents that still store `requiresAcknowledgement: true` map to
 
 ## Models
 
-- **Announcement** — `title`, `body` (markdown), `status` (`draft` | `published` | `archived`), `version`, `priority`, `displayMode` (`modal` | `banner` | `feed`, default `modal`), `audienceType` (`staff` | `patient` | `all`, default `all`), `acknowledgementPolicy`, optional `minBuildNumber`, `audience` (Mixed), `publishAt`, `expiresAt`, `platforms`, `primaryAction`
+- **Announcement** — `title`, `body` (markdown), `status` (`draft` | `published` | `archived`), `version`, `priority`, `displayMode` (`modal` | `banner` | `feed`, default `modal`), `audienceType` (`staff` | `patient` | `all`, default `all`), `acknowledgementPolicy`, optional `minBuildNumber`, `audience` (Mixed), `publishAt`, `expiresAt`, `platforms`, `primaryAction`, and optional imported `release` metadata plus `releaseSlug`
 - **AnnouncementAcknowledgement** — per-user acknowledgement at a specific `version`
 - **AnnouncementImpression** — per-view analytics row
 - **AnnouncementClickEvent** — per-click analytics row (`action: "primaryAction"`, `version` at click time, optional `platform`)
@@ -83,7 +84,7 @@ The plugin applies `matchAudienceByType` before `matchAudience`. When `isStaff`
 | GET | `/announcements/pending` | Current interrupt (`modal` or `banner` only) + `remainingCount` (`platform` query: `ios` \| `android` \| `web`; optional `version` build number) |
 | GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above) |
 | POST | `/announcements/:id/acknowledge` | Record acknowledgement (idempotent per version). Same visibility as pending/feed; **404** when not visible. |
-| POST | `/announcements/:id/impression` | Record a view. Same visibility as pending/feed; **404** when not visible. |
+| POST | `/announcements/:id/impression` | Record a view (`{ platform? }`). Same visibility as pending/feed; **404** when not visible. **400** for unknown keys or an invalid `platform`. |
 | POST | `/announcements/:id/click` | Record a primary-action click (`{ action: "primaryAction", platform? }`; optional `?version=` for min-build visibility). Returns **404** when not visible (checked before action/CTA validation). **400** when `action` is invalid, `primaryAction` is absent, or an explicit `platform` value is invalid. |
 
 `current` and feed items include resolved `requiresAcknowledgement` (boolean) and `displayMode` derived from policy resolution and stored fields above.
@@ -96,7 +97,7 @@ Optional integer build number on `GET /pending`, `GET /feed`, and help routes. W
 - `?version=10` (or higher) shows it
 - omitting `version` does **not** hide gated items
 
-`POST /announcements/:id/acknowledge`, `POST /announcements/:id/impression`, and `POST /announcements/:id/click` use the same visibility rules as pending/feed (schedule, expiry, platform, min build, `audienceType`, and `matchAudience`). All three return **404** when the announcement is not visible to the caller, so targeted IDs cannot be confirmed by writing event rows. Click checks visibility before action/CTA validation. Returns **400** when `action` is not `"primaryAction"`, the announcement has no `primaryAction`, or an explicit body `platform` is not `ios` / `android` / `web` (omit `platform` to use query/user-agent resolution). Each click inserts a new row (not idempotent). Acknowledge is idempotent per `(userId, announcementId, version)`.
+`POST /announcements/:id/acknowledge`, `POST /announcements/:id/impression`, and `POST /announcements/:id/click` use the same visibility rules as pending/feed (schedule, expiry, platform, min build, `audienceType`, and `matchAudience`). All three return **404** when the announcement is not visible to the caller, so targeted IDs cannot be confirmed by writing event rows. Impression and click bodies are validated with strict Zod schemas (`{ platform? }` and `{ action: "primaryAction", platform? }`); unknown keys or invalid values return **400** `Validation failed` with per-field messages in `meta.fields`. Click validates `platform` first, then checks visibility before validating `action` and the CTA. Returns **400** when `action` is not `"primaryAction"`, the announcement has no `primaryAction`, or an explicit body `platform` is not `ios` / `android` / `web` (omit `platform` to use query/user-agent resolution). Each click inserts a new row (not idempotent). Acknowledge is idempotent per `(userId, announcementId, version)`.
 
 ## Admin routes
 
@@ -104,9 +105,12 @@ Admin CRUD is on `/announcements` via `modelRouter`. Custom actions:
 
 - `GET /announcements/config` — returns `{ data: { defaultAcknowledgementPolicy } }` from the plugin constructor (admin only; defaults to `"dismiss-only"` when omitted). Used to pre-fill the admin editor acknowledgement policy field.
 - `GET /announcements/overview` — paginated admin dashboard with per-announcement metrics and aggregate totals. Access uses `adminOverviewPermissions` (defaults to `IsAdmin`). Query: `page` (default `1`), `limit` (default `20`, max `100`).
+- `POST /announcements/import-release` — idempotently imports up to 100 announcements keyed by release product/version/channel plus slug. Admin auth or the configured `uploadToken` bearer token is required. New items default to draft; request `publish: true` to publish them. The example deployment's token is `terreno-example-announcement-upload`, seeded by Terraform.
 - `POST /announcements/:id/publish` — draft → published
 - `POST /announcements/:id/archive` — published → archived
 
+See [Announcement release packs](announcement-release-packs.md) for the Markdown/frontmatter format, JSON request shape, version rules, and draft/live behavior.
+
 ### `GET /announcements/overview`
 
 Admin-only list for launch dashboards. Includes **all** lifecycle statuses (`draft`, `published`, `archived`). Soft-deleted announcements and event rows are excluded.

package/dist/docs/versioned/next/reference/api.md

@@ -222,6 +222,7 @@ export const todoRouter = modelRouter("/todos", Todo, {
 ```
 
 Do not add `endpoints: (router) => { router.get(...) }` when an action fits.
+Action config supports `allowAnonymous: true` as a per-action override; it does not change authentication for CRUD or sibling actions.
 
 ## modelRouter array operations
 

package/dist/docs/versioned/next/reference/environment-variables.md

@@ -239,6 +239,7 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
 | `ADMIN_SPA_ENABLED` | example-backend | ❌ | — | No | server |
+| `ANNOUNCEMENTS_UPLOAD_TOKEN` | example-backend `AnnouncementsApp` | ❌ | example deploy: `terreno-example-announcement-upload` | Yes outside the example app | server |
 | `ADMIN_SPA_DIST_DIR` | example-backend Dockerfile | ❌ | — | No | server |
 | `ADMIN_SPA_DEV_PROXY` | admin-spa plugin | ❌ | — | No | server |
 | `ADMIN_SPA_BACKEND_URL` | admin-spa tests | ❌ | — | No | tooling |

package/dist/docs/versioned/next/reference/ui.md

@@ -320,9 +320,17 @@ images once per mount.
 ### SplitPage
 
 Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list, and
-`renderContent` for the detail pane. On large screens both panes stay visible. On small
+`renderContent` or children for the detail pane. On large screens both panes stay visible. On small
 screens the detail replaces the list until the user goes back.
 
+`desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
+are one or two children. `narrowViewportChildLabels` opts into a labeled full-width pager on
+the narrow viewport. `narrowBelowWidth` uses that viewport when the window is at or below the
+given pixel width; when omitted, the narrow viewport follows `isNarrowViewport()`. These props
+are web only; the native `SplitPage` ignores them. See `SplitPageProps` for when each prop
+applies and what is ignored.
+`IconButton`'s `backgroundOpacity` tints only that button's background.
+
 ```typescript
 import {SplitPage, Text} from "@terreno/ui";
 
@@ -627,7 +635,7 @@ import {
   mediaQuery,
   mediaQueryLargerThan,
   mediaQuerySmallerThan,
-  isMobileDevice,
+  isNarrowViewport,
 } from "@terreno/ui";
 
 // Read the current breakpoint
@@ -645,9 +653,9 @@ if (mediaQuerySmallerThan("lg")) {
   console.log("Smaller than large");
 }
 
-// Detect mobile
-if (isMobileDevice()) {
-  console.info("Running on mobile device");
+// Current window is below the desktop breakpoint
+if (isNarrowViewport()) {
+  console.info("Narrow viewport");
 }
 ``````
 
@@ -673,7 +681,7 @@ Web (desktop staff):
 
 On web, `sm` (320) and `md` (375) still classify widths below 1024 so layouts can remain accessible.
 
-`isMobileDevice()` is true below the supported desktop floor: native width < 1024 (`xl`), web width < 1024 (`lg`).
+`isNarrowViewport()` is true below the supported desktop floor: native width < 1024 (`xl`), web width < 1024 (`lg`). `isMobileDevice()` is the same check and is deprecated in favor of `isNarrowViewport`.
 
 Responsive `Box` direction props update automatically when the window resizes or a device rotates:
 

package/dist/docs/versioned/next/tasks/demo-workshop.md

@@ -0,0 +1,150 @@
+# Task List: Demo workshop
+
+See: [`docs/implementationPlans/demo-workshop.md`](../implementationPlans/demo-workshop.md)
+
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Work the frontier: any task whose blockers are complete. The tracer is Task 1.1 (Button).
+- Do not start iOS work, a translation catalog, or an addon API.
+- Docs named on a task ship in that task. Use the `update-docs` skill.
+- UI tasks also use `verify-ui-changes` and `terreno-ui`.
+- Visual tasks use `review-chart-visuals` for the PNG diff workflow, then the new demo how-to.
+- Run the task's verification command before handoff. `bun run lint` and `bun run demo:compile` on every demo task.
+
+## Phase 1: Catalog, snippets, and preview bar
+
+- [x] **Task 1.1**: Button catalog contract
+  - Delivers: Button has a copyable usage snippet, resolvable related links, stable stories, one declarative interaction list, and typed control defaults.
+  - Files: `demo/demoConfig.tsx`, `demo/story-config/Button.config.tsx`, `demo/stories/Button.stories.tsx`, `demo/collectRegisteredStoryRenders.ts`, `demo/app/demo/[component].tsx`, `demo/README.md`
+  - Blocked by: none
+  - Acceptance: a unit test fails when a related name does not resolve, when an excluded story has an empty reason, or when a boolean control defaults to `""`. Button's snippet renders and copies. `showInDemo: false` hides a Button story in demo mode and leaves it on the dev route.
+  - Verification: `bun test demo/collectRegisteredStoryRenders.ts demo/demoConfig` (or the new colocated test), `bun run demo:compile`, and a web demo pass that opens Button, copies the snippet, and follows one related link.
+  - Docs: `demo/README.md` catalog-contract section
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.2**: Search, categories, and related links
+  - Delivers: the home grid and dev index filter by text and category, and every component's related row is links.
+  - Files: `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`, `demo/app/demo/[component].tsx`, story configs whose `related` strings do not resolve, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: searching "button" shows Button; choosing a category hides other categories; a broken related name fails the catalog test; the home grid still does not nest pressables (`demo/components/DemoCard.test.tsx`).
+  - Verification: catalog unit test, `demo/components/DemoCard.test.tsx`, and a web demo pass of search, category filter, and a related link.
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.3**: Usage snippet on every component
+  - Delivers: every registered story config has `usageExample`, and the component page can copy it.
+  - Files: `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`, `scripts/check-demo-coverage.ts` or a sibling check, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run check:demo-coverage` (or the new snippet check it calls) fails when any registered config lacks a non-empty `usageExample`. The Button page copy control still works.
+  - Verification: the check command, plus one web copy action on a second component (TextField).
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [x] **Task 1.4**: Preview toolbar and URL state
+  - Delivers: demo and dev component routes change theme, viewport, background, locale, right-to-left, and reduced motion from the URL. Embeds apply that state and hide the bar.
+  - Files: `demo/components/DemoChrome.tsx`, `demo/app/_layout.tsx`, `demo/app/demo/_layout.tsx`, `demo/app/dev/_layout.tsx`, `demo/contexts/EmbedModeContext.tsx`, `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: Button at a documented query uses the dark remap and the 375 viewport. Consent or date stories that already read locale receive the toolbar locale. Embed hides the bar. Reloading keeps the query.
+  - Verification: a focused demo unit test for query parse/serialize, `bun run demo:compile`, and a web demo pass of the Button query plus one embed URL.
+  - Docs: `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+## Phase 2: Web proof and health
+
+- [ ] **Task 2.1**: Web interaction and axe for Button
+  - Delivers: Playwright runs Button's step list and axe against the Button stories.
+  - Files: `scripts/demo/runWebStoryChecks.ts`, `demo/story-config/Button.config.tsx`, root `package.json` (axe dependency if needed), `.circleci/config.yml`, `.circleci/continue-config.yml`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Blocked by: Task 1.1
+  - Acceptance: the Button interaction steps pass in Chromium. A serious axe violation fails the command. An excluded story with a reason is skipped. The job is required for `ui/**` and `demo/**` pull requests.
+  - Verification: `bun run demo:web-checks --only=Button` (the script this task adds) locally against demo web, then the CircleCI path-filter test if one exists beside `.circleci/`.
+  - Docs: `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 2.2**: Web visual harness for Button
+  - Delivers: one cropped web PNG baseline for each stable Button story, compared with the chart pixel matcher.
+  - Files: `scripts/demo/compareDemoSnapshots.ts`, `demo/rendered-snapshots/web/`, `scripts/charts/compareChartImages.ts` (reuse only), `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run demo:snapshots:compare --only=Button` passes against the new goldens and fails when a golden is missing. Chart compare still passes for the existing chart fixtures.
+  - Verification: the new compare command and `bun run ui:charts:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`, `docs/how-to/compare-chart-rendered-snapshots.md` (pointer only)
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.3**: Web proof for every stable story
+  - Delivers: every stable story has interaction steps or an exclusion reason, an axe run, and a web PNG baseline.
+  - Files: `demo/story-config/*.config.tsx`, `demo/stories/*.stories.tsx`, `demo/rendered-snapshots/web/`, the web check and snapshot scripts
+  - Blocked by: Task 2.1, Task 2.2
+  - Acceptance: the web check and snapshot commands, with no `--only`, exit 0. Removing one stable story's golden or steps fails the matching command. Excluded stories name a reason.
+  - Verification: `bun run demo:web-checks` and `bun run demo:snapshots:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.4**: Story health and CI summary
+  - Delivers: the component page shows render, interaction, accessibility, and visual status from `demo/story-health.json`. CI stores that file and writes a check summary.
+  - Files: `demo/app/demo/[component].tsx`, `scripts/demo/writeStoryHealth.ts`, `.circleci/continue-config.yml`, `docs/reference/test.md`
+  - Blocked by: Task 2.3
+  - Acceptance: Button shows a pass row after the web commands. A forced failing story shows fail. A missing health file shows not-run. The CircleCI job summary lists failed story ids. The job does not call `gh pr comment`.
+  - Verification: unit test for health rendering, the web commands, and a CI config test or review that the job uploads artifacts and writes the summary.
+  - Docs: `docs/reference/test.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+## Phase 3: Android
+
+- [ ] **Task 3.1**: Android proof for Button
+  - Delivers: a CircleCI Android emulator job runs Button's steps, accessibility-tree assertions, and a cropped Android PNG.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/demo/generateMaestroFlows.ts`, `.maestro/flows/demo/generated/`, `demo/rendered-snapshots/android/`, `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`
+  - Blocked by: Task 2.1
+  - Acceptance: Pixel 6 API 34 runs the generated Button flow. The job is required when `ui/**` or `demo/**` changes. A missing Android golden fails the job. Web axe is unchanged.
+  - Verification: the local Maestro command documented in the how-to, against an emulator, for the Button flow. Record the CircleCI job name.
+  - Docs: `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 3.2**: Android proof for every stable story
+  - Delivers: every stable story has an Android flow, accessibility-tree check, and PNG, or an exclusion reason.
+  - Files: generated Maestro flows, `demo/rendered-snapshots/android/`, `demo/story-health.json` writer
+  - Blocked by: Task 3.1, Task 2.3
+  - Acceptance: the Android job without `--only` exits 0. Health on Button includes the Android columns. An excluded story is absent from the Android failure list and its reason is in the summary.
+  - Verification: the Android compare and Maestro commands across the stable catalog.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+## Phase 4: Major versions
+
+- [ ] **Task 4.1**: Version manifest and dropdown
+  - Delivers: production stays on the current major, `versions.json` lists released majors and a `preview/<major>` branch, and the top bar dropdown navigates there. The default is the highest released major.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `scripts/ci/netlify-deploy.sh`, `demo/components/DemoChrome.tsx`, `docs/how-to/demo-versions.md`, `.circleci/continue-config.yml`
+  - Blocked by: Task 1.4
+  - Acceptance: a unit test of the manifest builder marks `preview/58` as preview and not current, marks 57 as current, and omits `pr-*` aliases. The dropdown on the home page shows those labels. `versions.json` on the production origin sends CORS headers the aliases can read.
+  - Verification: the manifest unit test, a deploy dry-run, and a web demo pass of the dropdown.
+  - Docs: `docs/how-to/demo-versions.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 4.2**: Freeze the previous major and backfill 56
+  - Delivers: moving master from 57 to a later major freezes 57 on alias `v57`. Alias `v56` serves the last master commit whose package major is 56.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `.circleci/continue-config.yml`, `docs/how-to/demo-versions.md`
+  - Blocked by: Task 4.1
+  - Acceptance: a test with a fake deploy history freezes the previous production deploy when the major increases, and leaves 57 updating on ordinary master commits. The backfill command documents the git revision it deployed for 56.
+  - Verification: unit test of the freeze decision, plus the one-time 56 alias deploy recorded in the how-to.
+  - Docs: `docs/how-to/demo-versions.md`
+  - Skills: `update-docs`
+
+- [ ] **Task 4.3**: Docs embeds follow the demo major
+  - Delivers: a 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when the manifest lists it.
+  - Files: `website/docusaurus.config.ts`, `website/src/components/ComponentDemo/index.tsx`, `docs/how-to/demo-versions.md`, the docs reference page that describes component embeds
+  - Blocked by: Task 4.1
+  - Acceptance: `ComponentDemo` for the 57 docs build requests the 57 demo URL with `?embed=1`. When the manifest has an unreleased preview, the next docs build uses that preview URL. A missing preview falls back to production.
+  - Verification: a website unit test or build-arg test for the URL choice, and `bun run website:build`.
+  - Docs: `docs/how-to/demo-versions.md` and the existing component-embed reference section
+  - Skills: `update-docs`
+
+## Phase 5: MCP catalog
+
+- [ ] **Task 5.1**: Public demo catalog tools
+  - Delivers: `terreno_list_demo_stories` and `terreno_get_demo_story` return Button's snippet, route, story ids, and the version manifest URL.
+  - Files: `demo/demo-catalog.json`, `demo/package.json`, `mcp-server/src/tools.ts`, MCP tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.3, Task 4.1
+  - Acceptance: `terreno_get_demo_story` for Button includes `usageExample` and a `/demo/Button` route. The list tool filters by category. The response points at production `versions.json`. A catalog drift test fails when a registered component is missing from the JSON.
+  - Verification: `cd mcp-server && bun test` for the new tool tests, and `bun run demo:catalog` followed by the drift check.
+  - Docs: `docs/reference/mcp-server.md`, `demo/README.md`
+  - Skills: `update-docs`

package/package.json

@@ -11,7 +11,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.7.0",
+    "@terreno/api": "57.8.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -104,5 +104,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.7.0"
+  "version": "57.8.0"
 }

package/src/docs/resources/ui.md

@@ -253,7 +253,7 @@ radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radius3xl
 ## Utilities
 
 ```typescript
-import { useStoredState, MediaQuery, isMobileDevice } from "@terreno/ui";
+import { useStoredState, MediaQuery, isNarrowViewport } from "@terreno/ui";
 
 // Persist state to storage
 const [value, setValue] = useStoredState("key", defaultValue);
@@ -263,9 +263,10 @@ const [value, setValue] = useStoredState("key", defaultValue);
   <DesktopLayout />
 </MediaQuery>
 
-// Device detection
-if (isMobileDevice()) {
-  // Mobile-specific code
+// Current window is below the desktop breakpoint.
+// isMobileDevice() is deprecated in favor of isNarrowViewport().
+if (isNarrowViewport()) {
+  // Narrow-viewport code
 }
 ```
 

package/src/docs/upgrades/57.8.0.md

@@ -0,0 +1,61 @@
+# Upgrading to 57.8.0
+
+**Action required:** No
+**Affected packages:** @terreno/ui, @terreno/announcements
+
+## Summary
+
+Bump every lockstep `@terreno/*` package together to `57.8.0`. `@terreno/ui` adds opt-in `SplitPage` web layouts and `IconButton` `backgroundOpacity`, and deprecates `isMobileDevice` in favor of `isNarrowViewport` (the old function still returns the same result). `@terreno/announcements` can import a Markdown release pack through `POST /announcements/import-release`. `DropdownPanel` anchors to its trigger, and `/gpt/prompt` emits each generated image once. No Expo upgrade is required if you are already on `57.x`.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+### `isMobileDevice`
+
+**What changed**
+
+`isMobileDevice` is deprecated. `isNarrowViewport` is the supported name. Both stay exported and return the same boolean: true when the window is below the supported desktop floor (web width under 1024, native width under 1024).
+
+**Why**
+
+`isMobileDevice` described a window-width check. The new name matches that behavior.
+
+**Migration**
+
+```typescript
+// Before
+import {isMobileDevice} from "@terreno/ui";
+
+if (isMobileDevice()) {
+  // narrow layout
+}
+
+// After
+import {isNarrowViewport} from "@terreno/ui";
+
+if (isNarrowViewport()) {
+  // narrow layout
+}
+```
+
+## New capabilities
+
+`SplitPage` web props are opt-in. Existing callers keep the previous layout.
+
+- `desktopChildrenMinWidth` keeps one or two desktop children at least that many pixels wide and scrolls the row when it is tighter. More than two children keeps the segmented control.
+- `narrowViewportChildLabels`, `narrowViewportSelectionActive`, `narrowViewportSelectionKey`, and `narrowViewportListButtonLabel` replace the dotted narrow swiper with a labeled pager.
+- `narrowBelowWidth` uses the narrow layout when the window width is less than or equal to that pixel value. Omit it to follow `isNarrowViewport()`.
+- Native `SplitPage` ignores these props.
+- `IconButton` `backgroundOpacity` tints only that button's background.
+
+`@terreno/announcements` accepts a `terreno.announcement-pack/v1` directory (`pack.yaml` plus one Markdown file per announcement) at `POST /announcements/import-release`. Imports are idempotent by product, release version, channel, and slug, default to drafts, and publish immediately when `publish: true`. Admin auth or bearer `ANNOUNCEMENTS_UPLOAD_TOKEN` can call the route. The token is optional.
+
+## Verification
+
+- `bun add` every lockstep `@terreno/*` dependency to `57.8.0`, then `bun run compile` at the app root
+- Replace `isMobileDevice` imports with `isNarrowViewport` before a future major removes the alias
+- Open a `DropdownPanel` whose trigger is not at the start of its row and confirm the panel opens on the trigger
+- Import a draft announcement pack with `POST /announcements/import-release` and confirm a second import updates the same slug instead of inserting a duplicate

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -20,6 +20,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
 | File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/gcs-settings.tsx` | |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -101,7 +101,7 @@ HTTP method and scope map to a CRUD permission check:
 **403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
 **401** — unauthenticated when a permission requires auth (from existing auth middleware).
 
-`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD.
+`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD. An action may set `allowAnonymous: true` to accept unauthenticated requests without making the router's CRUD routes or other actions anonymous. Keep a non-empty permission such as `Permissions.IsAny` and authenticate any service token in the handler.
 
 ## Validation
 

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -1257,6 +1257,20 @@ IP and tracking issue; this entry is the release checklist, not a plan.
 
 ---
 
+## demo-workshop
+
+**Title:** `Demo workshop`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`demo-workshop`, Status=`Planned`
+
+Turn the Expo demo into the workshop for `@terreno/ui`: a person can find a component, copy a usage snippet, change theme and viewport from the URL, and see whether every stable story passes interaction, accessibility, and visual checks on web and Android.
+
+- **Implementation plan:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/demo-workshop.md)
+- **Tasks:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/demo-workshop.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/src/docs/versioned/next/how-to/circleci.md

@@ -351,20 +351,35 @@ a closed PR.
 `manual-publish-package` also accepts `feature-flags`. Versions must be semver.
 Semver git tags (`57.3.0`, `57.3.0-beta.1`) automatically start
 `publish-release`; prereleases publish to their prerelease npm dist-tag.
-`scripts/ci/publish-package.sh` pins `workspace:*` to the tag version for the
-tarball, then compiles and tests against the root workspace install. It must
-not `bun install` after that pin: sibling `@terreno/*` packages are not on npm
-yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on the registry
-and fail the whole job. Tests use `test:ci` when that script exists, not
-`test`. `@terreno/ui`'s `test` is `bun test --watch` and would hang the
-publish step after the suite finishes. `publish-release` uses a 20-minute
-no-output timeout as a backstop. If a package's tag version is already on npm,
-`publish-package.sh` skips it so a recut of the same tag can finish the rest.
-
-Only stable tags (`57.3.0`) run `deploy-demo` after publish. Use
+`publish-release` compiles the 16 lockstep packages once with
+`bun run --filter ... compile` (dependency order), then runs
+`scripts/ci/publish-package.sh` for all of them in parallel with
+`TERRENO_PUBLISH_PREBUILT=1`. It does not rerun tests: the tagged commit
+already passed CI on master, and rerunning every suite per package made
+releases take 20+ minutes. The job has no Mongo sidecar. Each publish writes
+its own temporary npmrc (`NPM_CONFIG_USERCONFIG`) so parallel publishes do not
+remove each other's token.
+
+`publish-package.sh` pins `workspace:*` to the tag version for the tarball.
+It must not `bun install` after that pin: sibling `@terreno/*` packages are
+not on npm yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on
+the registry and fail the whole job. Without `TERRENO_PUBLISH_PREBUILT` (the
+manual single-package publish), it compiles the package and its workspace
+dependencies and runs `test:ci` when that script exists, not `test`.
+`@terreno/ui`'s `test` is `bun test --watch` and would hang. If a package's
+tag version is already on npm, `publish-package.sh` skips it so a recut of
+the same tag can finish the rest.
+
+Only stable tags (`57.3.0`) run `deploy-demo`. It builds the demo from source,
+so it runs alongside `publish-release` instead of waiting for it. Use
 `{"run-demo-deploy":true}` on `master` if a prerelease must also refresh the
 demo site.
 
+`scripts/ci/netlify-deploy.sh` builds each site itself and calls
+`netlify deploy --no-build`. Without `--no-build`, netlify-cli runs the root
+`netlify.toml` docs build (wipe `node_modules`, reinstall, full Docusaurus),
+which added about 3.5 minutes to every demo and frontend deploy.
+
 CircleCI does not receive GitHub `pull_request.closed` events, so
 `.github/workflows/preview-cleanup.yml` forwards them: it runs master's
 `scripts/ci/trigger-circleci-pipeline.sh` with `{"run-preview-cleanup":"<PR>"}`

package/src/docs/versioned/next/how-to/preview-demo.md

@@ -0,0 +1,19 @@
+# Preview a component demo
+
+Open a component demo and change the shareable query. The preview bar is on demo and
+dev component routes. `?embed=1` applies the same query and hides the bar.
+
+```text
+/demo/Button?theme=dark&viewport=375&background=inverse&locale=en-US&rtl=1&reducedMotion=1
+```
+
+| Query | Values |
+| --- | --- |
+| `theme` | `light` (default) or `dark` (canonical dark role remap) |
+| `viewport` | `full` (default), `320`, `375`, `1024`, `1280` |
+| `background` | `default`, `inverse`, `transparent` |
+| `locale` | Passed to components that already read a locale, such as consent |
+| `rtl` | `1` sets document direction to `rtl` on web |
+| `reducedMotion` | `1` sets `data-reduced-motion="1"` on the document element |
+
+Reload keeps the query. The bar shows the current query when any value is not the default. Choosing a control's default removes that key from the URL. Leaving the component route restores the app theme and, on web, document direction and reduced motion. Custom palettes stay on `/palette`.

package/src/docs/versioned/next/how-to/product-announcements.md

@@ -11,6 +11,7 @@ import {AnnouncementsApp} from "@terreno/announcements";
 
 new AnnouncementsApp({
   defaultAcknowledgementPolicy: "dismiss-only",
+  uploadToken: process.env.ANNOUNCEMENTS_UPLOAD_TOKEN,
   // audienceType staff/patient/all is applied inside the plugin via matchAudienceByType.
   isStaff: (user) => (user as {admin?: boolean}).admin === true,
   matchAudience: (user, announcement) => {
@@ -46,6 +47,8 @@ For Flourish-style surfaces on one collection:
 
 2. Create announcements in admin (draft → publish). Use `AnnouncementOverview`, `AnnouncementEditor`, and (optionally) `AnnouncementList` from `@terreno/admin-frontend` with dedicated Expo routes (see `example-frontend/app/admin/announcements/`). The built-in admin screen widget key `announcements` renders the overview when your host uses `AdminScreenRouter` for custom screens. Published `title`/`body` edits auto-increment `version`, which re-shows the surface to users who only acknowledged the previous version.
 
+For release-driven batches, use an [announcement release pack](../reference/announcement-release-packs.md). It keeps one `pack.yaml` manifest plus multiple Markdown announcements in source control, validates release and build versioning, and can import idempotent drafts or explicitly publish the whole pack through a dedicated bearer token. The example Cloud Run service accepts `Authorization: Bearer terreno-example-announcement-upload` (Terraform variable `announcements_upload_token`).
+
 ### Admin editor fields
 
 `AnnouncementEditor` exposes structured targeting controls (no raw `requiresAcknowledgement` boolean):