@sempods/apps 0.8.0-dev.1 → 0.9.0-dev.1

package/CHANGELOG.md

@@ -4,6 +4,172 @@ Each release lists what changed and **upgrade notes** for the assistant that
 applies it. The notes cover what an update cannot decide alone: owner files,
 configuration choices and the SDK migration.
 
+## 0.9.0
+
+Prerelease `0.9.0-dev.1` for acceptance testing against SDK `0.7.0-dev.2`.
+
+### Changes
+
+SDK and UI kit:
+
+- New repositories use SDK 0.7.0-dev.2 (`@sempods/app-sdk`,
+  `@sempods/client-sdk`) and the UI kit `@sempods/app-ui` of the same
+  version, which is released with the SDK. `@sempods/apps` supports
+  `^0.7.0-dev.2` of all three. The UI kit is shadcn/ui (style aria-nova) on
+  React Aria for Tailwind CSS 4, with sempods adapters (`ScreenDialog`,
+  `HeaderMenu`, `DateChooser`, `ActionButton`/`ActionLink`/`ActionGroup`,
+  `ChipGroup`/`Chip`), the router `useNav` and a theme token contract with a
+  bridge to the SDK's tokens. Kit fixes reach apps through its version.
+- The UI kit joins the SDK in `update-policy.json` (`sdk`): the root declares
+  it, an app declares it when it uses it, and `check` requires one version
+  for all of them. `sdk-update` moves it with the SDK packages, adds it to a
+  root that lacks it, checks that the release supports the SDK and moves it
+  in an app only where the app declares it. `new-app` gives a new app the
+  root's version. The Dependabot SDK groups include it. `build-site`
+  publishes its licence notices with the apps that use it.
+- The migration never adds the UI kit to a root at an SDK version that has
+  none (before 0.7.0); its report says that `sdk-update` adds it.
+
+Skeleton:
+
+- Tailwind CSS 4 (`tailwindcss`, `@tailwindcss/vite`) and `@sempods/app-ui`.
+  `src/index.css` declares the layer order
+  `@layer theme, base, sempods, components, utilities;`, then imports
+  Tailwind, the UI kit's styles and the app's theme; `main.tsx` imports only
+  `index.css`. `vite.config.ts` adds the Tailwind plugin and raises Vite's
+  chunk warning to 1000 kB: React, the SDK and the UI kit come to about
+  570 kB minified (180 kB gzip) in one chunk.
+- The four themes in `src/themes/` set the palette roles of the theme
+  contract (`--background`, `--foreground`, `--card`, `--popover`,
+  `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`,
+  `--border`, `--input`, `--ring` with their foregrounds) in light and dark
+  mode, instead of the `--sempods-*` tokens, which the kit's bridge now sets.
+  Each passes `check:theme` in every action variant. Action variants switch
+  with `data-actions` and `data-secondary` on `<html>`. The icon takes the
+  theme's primary colour.
+- The copied kit in `src/ui/` and the router in `src/routes.ts` are gone.
+  `src/places.ts` is the app's address model (start page, a view per route,
+  an item per resource address with its source Context, the callback and an
+  explicit not-found place), and `App.tsx` routes with `useNav(places)`,
+  passes the kit's `replaceUrl` to the runtime through `inApp`, uses
+  `HeaderMenu` for the menu and shows a not-found page once the person is
+  connected. `inApp` keeps the return of a callback without a matching
+  sign-in, for example an expired one, in the app: the SDK returns such a
+  callback to `/`, the site's overview, when `returnTo` is a function.
+- `src/examples/ListScreen.tsx` is rebuilt on the kit: each item has its own
+  address and opens in a `ScreenDialog` with the SDK's editor for the Context
+  the address names; closing returns to the opener and reloads the list
+  without waiting for it. The input of the bar at the bottom keeps its focus
+  while it adds several items: read-only while a creation is pending and
+  focused from the submit handler, also after a press on Add
+  (sempods/sempods-apps-template#113).
+- `src/examples/ContextSwitch.tsx` replaces `ui/ContextSwitch.tsx`, built on
+  the kit's menu parts.
+
+Addresses:
+
+- `routes` in `apps.json` takes literal addresses of up to four segments
+  (`tasks/add`); `build-site` writes their copies in subfolders.
+- `resources` (new) declares patterns with placeholders for one segment each
+  (`tasks/:id`, `tasks/:id/postpone`). The first segment is a word, so a
+  pattern never catches the callback or the app's files; patterns that name
+  the same addresses are refused. `build-site` writes `site-dist/_redirects`
+  with one rewrite per pattern to the app's page, for hosts that read it
+  (Netlify, Cloudflare Pages).
+- The PWA navigation allowlist covers the start page, every route and every
+  resource pattern, each with an optional query: Workbox matches path and
+  query, so the start page with a query and every resource address now open
+  offline.
+- Sign-in returns to the address it started from with its query when the app
+  declares it (start page, route or resource), otherwise to the start page,
+  also in an app without routes. It drops the callback's parameters (`code`,
+  `state`, `error`, `iss`, `response`), which the SDK refuses in a return
+  address, and keeps the rest of the query. The generated `returnTo` is now a
+  function for every app.
+
+Tooling:
+
+- `pnpm run check:theme [<id>]` (new; `sempods-apps check-theme`) builds each
+  app that uses the UI kit, loads its stylesheet with the attributes of its
+  `<html>` in Chromium and runs the kit's role check under a light and a dark
+  preference, for every action variant. It prints one line per failing pair
+  with the variants, colours, ratio and roles to adjust, reports a scheme the
+  theme excludes as not sampled, prints the reports with `--json` and fails on
+  any contrast failure or checker error. Playwright is a dependency of
+  `@sempods/apps`; `--install-browser` installs its Chromium once.
+- `migrate` names every app that still has the kit copied in 0.8.0, with the
+  files that are as shipped and those the owner changed. It changes none of
+  them.
+
+Instructions:
+
+- The app workflow, the skill's visual check and the publish guide name the
+  kit's components and adapters, the theme contract and `check:theme`, the
+  address model with `routes` and `resources`, the source Context in resource
+  addresses and the rewrite requirement for resource patterns. A component
+  the kit lacks comes from `shadcn add` and is the app's own; copying a kit
+  component to change it is a recorded decision.
+
+### Upgrade notes
+
+1. After `migrate`, `check` reports the SDK as outside the supported range
+   and, at the root, the missing `@sempods/app-ui`. Run
+   `pnpm run sdk-update <version>` with the SDK release this tooling names
+   (now `0.7.0-dev.2`); it adds the UI kit to the root. Then follow the SDK's
+   `migration.md`, "From 0.6.0 to 0.7.0": its styles now sit in the cascade
+   layer `sempods`, so check the sign-in screen, the Pods & sharing dialog, an
+   editor and a confirmation with each app's real stylesheet.
+2. `pnpm run regenerate` (the migration runs it) widens the offline
+   allowlist to addresses with a query and keeps the query on sign-in, also
+   in an app without routes. Its `returnTo` is then a function, so a
+   callback without a matching sign-in returns to `/`, the site's overview.
+   Keep it in the app where `App.tsx` creates the runtime:
+   `replaceUrl: (url) => replaceUrl(url.startsWith(app.basePath) ? url : app.basePath)`,
+   or `inApp` from the skeleton's `src/places.ts` once the app has it.
+3. An app with the copied kit keeps working; `check` does not require the UI
+   kit. Move it to the package only when the owner agrees, as its own pull
+   request, with the migration report's note for that app at hand:
+   1. `pnpm add --dir apps/<id> @sempods/app-ui@<the SDK version>
+      lucide-react@1.65.0` and
+      `pnpm add --dir apps/<id> -D tailwindcss@4.3.3 @tailwindcss/vite@4.3.3`.
+   2. Add `tailwindcss()` from `@tailwindcss/vite` to the plugins in
+      `vite.config.ts`, as the skeleton does
+      (`node_modules/@sempods/apps/skeleton/app/vite.config.ts`).
+   3. Take the skeleton's `src/index.css`, with the app's theme name in its
+      import line, and import only it in `src/main.tsx`. Move the app's own
+      global rules into `@layer base` or into Tailwind classes; an unlayered
+      element rule overrides every SDK rule.
+   4. A theme the app kept as shipped: copy the skeleton's theme of the same
+      name. A changed theme: carry its colours over to the palette roles
+      (`--sempods-bg` → `--background`, `--sempods-text` → `--foreground`,
+      `--sempods-muted` → `--muted-foreground`, `--sempods-line` →
+      `--border`, `--sempods-accent` → `--primary` and `--ring`,
+      `--sempods-on-accent` → `--primary-foreground`), add the other roles
+      from the skeleton's theme, give `--input` 3:1 against the surfaces, and
+      run `pnpm run check:theme <id>` until it passes.
+   5. Replace `src/routes.ts` with the skeleton's `src/places.ts` and
+      `places.test.ts`: a route `r` becomes `{ kind: 'view', route: r }`, the
+      start page `{ kind: 'start' }`; `useRoute()` becomes `useNav(places)`
+      once in the frame, `go(r)` `nav.go(place)`, `link(r)`
+      `nav.link(place)`, and `replaceUrl` comes from `@sempods/app-ui`,
+      passed to the runtime through `inApp` as the skeleton's `App.tsx` does.
+      Declare an item screen's address under `resources` and open it with
+      `ScreenDialog`, as the list example does.
+   6. Replace each kit part: `Menu` with `HeaderMenu`, `Dialog` with
+      `ScreenDialog`, `Composer` with the bar of the list example, `Tabs` with
+      links (`nav.link`) or a View submenu of `HeaderMenu`, `ContextSwitch`
+      with the skeleton's `src/examples/ContextSwitch.tsx`, the icons with
+      `lucide-react`. Delete the files the note lists as shipped once nothing
+      imports them. A file the note lists as changed holds the owner's own
+      work: carry that change over into the new composition, or keep the file
+      as the app's own and record that under Decisions in `NOTES.md`; ask the
+      owner which.
+   7. Run `pnpm run check`, `pnpm run check:theme <id>` and the visual check,
+      including Back, Escape and Close with an unsaved edit, and record them
+      in the app's `NOTES.md`.
+4. Apps with resource patterns need a host that reads `_redirects`; check
+   each resource address as the publish guide's deployment check describes.
+
 ## 0.8.0
 
 ### Changes
@@ -58,7 +224,7 @@ Look:
   `--sempods-*` tokens: `Menu` (a button with a list of actions or choices;
   Escape, a press outside and the arrow keys), `ContextSwitch` (the everyday
   switch between the contexts shared with the app over the SDK's
-  `useContexts`, in place of the app's name), `Tabs` (views as links with
+  `useContexts`, in place of the header's `<h1>`), `Tabs` (views as links with
   their routes), `Composer` (an input bar fixed at the bottom, above the home
   indicator and, where browsers support it, the on-screen keyboard), `Dialog`
   (modal, a bottom sheet on phones, for example around a `ResourceEditor`)
@@ -66,8 +232,9 @@ Look:
 - The skeleton ships `src/examples/ListScreen.tsx`, not mounted: the SDK's
   quickstart screen built with the kit (loading and failed reads, an empty
   state, rows with a labelled checkbox, the item's `ResourceEditor` in a
-  `Dialog`, `RemoveButton`, open outcomes and a `Composer`). It compiles with
-  every app, so it stays valid against the SDK.
+  `Dialog`, `RemoveButton`, open outcomes and a `Composer`, which a list the
+  person can only read does not show). It compiles with every app, so it
+  stays valid against the SDK.
 
 Content and configuration:
 
@@ -116,25 +283,29 @@ Content and configuration:
 
 Instructions:
 
-- The app workflow starts a new app with a short design conversation
-  (purpose, mood as a theme, name and icon), asked as choices with "choose for
-  me", and records it under Design in the app's `NOTES.md`; later wishes
-  change the recorded choice instead of adding one-off styles. It says which
-  parts of the look are shared (layout, kit) and which are chosen per app
-  (theme, name, icon).
-- The app workflow settles how an app uses contexts before its first screen:
-  one context, several one at a time, read all and write in one, or write
-  into several. It infers the shape or asks once in everyday words and starts
-  from the SDK's path for it (`AppAccess` or a preset, `useContexts` with
-  `ContextSwitch`, the Pod overview with `useCreation`, one `useCreation` per
-  context). The skeleton's `NOTES.md` has Design and Data sections, and setup
-  asks for one test context per context the shape uses.
+- App planning settles purpose, personal versus shared data and context
+  access limits before generation, with at most three short questions at a
+  time. The assistant proposes layout, theme, name and icon; a vague request
+  need not wait for visual choices. Decisions go into the app's `NOTES.md`.
+- The workflow chooses reusable data mappings from existing data and
+  established vocabularies, preserving identities and fields other apps use.
+  If the owner wants, optional read-only inspection through a connected MCP
+  Pod informs this choice within an agreed scope. Setup and the user guide
+  explain that MCP is optional and separate from signing in to the app;
+  app trials still use synthetic data in dedicated test contexts.
+- Before generation, the workflow settles what the app reads, where new
+  records go and where existing records are edited: one context, several one
+  at a time, read all and write in one, edit overview rows in their source
+  contexts, or write into several. It starts from the installed SDK's path
+  for that shape. The skeleton's notes record Data and Vocabulary decisions,
+  including observed mappings and assumptions still to verify. Setup asks
+  for one test context per context the shape uses.
 - The app workflow starts a list from the list example, takes only behaviour
   from the SDK's examples, deletes rows with `RemoveButton`, relies on the
   SDK's list refresh when the page becomes visible again, adds kit parts only
   when the app needs them, and describes routes, renaming and themes. It is
-  reordered: design conversation and `new-app`, context shape, vocabulary,
-  screen, views, configuration.
+  reordered: planning, optional data inspection, context shape, vocabulary,
+  `new-app`, screen, views, configuration.
 - A visual check before handover (`instructions/visual-check.md`): the
   assistant takes screenshots at 375px and desktop width, light and dark, with
   real states (empty, a few items, an open item, a notice), checks them
@@ -150,11 +321,12 @@ Instructions:
 1. The migration does by itself: it adds the root script `icon`, regenerates
    every app (`app.routes`, `app.description` as `null` until set, the
    manifest colours, the `pageTitle` plugin, the service worker's allowlist
-   for routes) and moves apps to the generated page title where that is
-   unambiguous, listed under "Updated". For any other app, `check` names what
-   is left: add `pageTitle` from `./vite.sempods.generated.ts` to the plugins
-   in its `vite.config.ts`, as the skeleton does, and remove the `<title>`
-   from its `index.html`. A page title other than the one in `apps.json` was
+   for routes), moves apps to the generated page title where that is
+   unambiguous and replaces the viewport and green `theme-color` lines an
+   app's `index.html` kept from the 0.7 skeleton, listed under "Updated". For
+   any other app, `check` names what is left: add `pageTitle` from
+   `./vite.sempods.generated.ts` to the plugins in its `vite.config.ts`, as
+   the skeleton does, and remove the `<title>` from its `index.html`. A page title other than the one in `apps.json` was
    chosen by hand: ask the owner whether it should be the app's title, put it
    into `apps.json` and run `pnpm run regenerate`. Settle these cases before
    the SDK move: `sdk-update` ends with `check` and stops on them.
@@ -191,8 +363,12 @@ Instructions:
      `document.documentElement.lang`), because `app.language` is then
      `"auto"`; read the app's texts from a catalogue with both languages
      through `useMessages`;
-   - Design and Data sections in `NOTES.md`, settling the context shape as the
-     app workflow describes.
+   - Design, Data and Vocabulary sections in `NOTES.md`, following the app
+     workflow. Check personal/shared access assumptions, reuse of existing
+     data and the separate destinations of new records and edits. Offer MCP
+     inspection only when existing data is relevant and the owner wants it;
+     record unverified assumptions when it is skipped. These instructions
+     do not migrate existing Pod data.
 
 ## 0.7.1
 

package/README.md

@@ -11,17 +11,19 @@ Create a repository with `pnpm create @sempods/apps <directory>`
 `sempods-apps create <directory>` of the same version. The repository's root
 `package.json` runs the other commands through `sempods-apps <command>`:
 
-- `pnpm run new-app <id>` creates `apps/<id>` with the root's SDK version.
+- `pnpm run new-app <id>` creates `apps/<id>` with the root's SDK version,
+  built with the UI kit `@sempods/app-ui`.
 - `pnpm run icon <id>` draws an app's monogram icon again in its theme's
-  accent.
+  primary colour.
 - `pnpm run dev <id>` starts that app.
 - `pnpm run regenerate` rewrites every app's generated configuration from
   `apps.json`, for example after a tooling update.
 - `pnpm run configure-site --production <origin>` records where the apps are
   published and regenerates their configuration.
 - `pnpm run build-site` builds all apps and the overview into one static site,
-  `site-dist/`.
-- `pnpm run sdk-update <version>` moves all apps to one SDK release.
+  `site-dist/`, with `_redirects` rewrites for the apps' resource addresses.
+- `pnpm run sdk-update <version>` moves all apps to one SDK release: the SDK
+  packages and the UI kit.
 - `pnpm run update [<version>]` checks that Node and pnpm suit the target
   version, installs it and runs its `migrate`. `pnpm run migrate` applies the
   installed version's starter to the repository from `.sempods-baseline.json`.
@@ -31,13 +33,18 @@ Create a repository with `pnpm create @sempods/apps <directory>`
 - `pnpm run check` checks all apps; `--standalone all` also installs, lints,
   builds and tests each app on its own. It reports an SDK version outside the
   range this package supports (its `peerDependencies`).
+- `pnpm run check:theme [<id>]` checks the contrast of each app's theme in
+  light and dark mode and every action variant, in Chromium through
+  Playwright; `--json` prints the reports, and `--install-browser` installs
+  the browser once.
 
 Contents:
 
 - `instructions/`: the setup procedure, the app workflow, the visual check and
   the publish guide; `skills/` holds the skill entries that route to them.
-- `skeleton/app/`: what a new app starts from, with its themes, UI kit and
-  list example. Files named `*.generated.ts` in
+- `skeleton/app/`: what a new app starts from: Tailwind CSS 4 and
+  `@sempods/app-ui`, its themes, its address model and the list and context
+  switch examples. Files named `*.generated.ts` in
   an app are written from `apps.json`; do not edit them. `check` reports any
   difference, and `regenerate` rewrites them.
 - `shared/`: the starter of this release, its files stored by content hash in

package/bin/sempods-apps.mjs

@@ -13,6 +13,7 @@ const COMMANDS = {
   'configure-site': 'record where the apps are published',
   'build-site': 'build all apps and the overview into site-dist/',
   check: "check the repository's apps",
+  'check-theme': "check the contrast of an app's theme in a browser",
   'sdk-update': 'move all apps to one SDK release',
   update: 'install a newer @sempods/apps and migrate to its starter',
   migrate: "apply the installed @sempods/apps' starter to this repository",