feat(desktop): build apps in project folders (plan 66, Part D)

.github/workflows/desktop-release.yml

@@ -312,6 +312,51 @@ jobs:
           } >> "$GITHUB_ENV"
           clang++-17 --version | head -1
 
+      # ── Step 3.6: the engine the app pins must be on npm ───────────────────────
+      #
+      # A new project made in the app installs `@adminiumjs/adminium` at the app's
+      # own version, from npm. An app released before that version is published
+      # makes projects that cannot be made. On a real tag its absence stops the
+      # release; on a manual run of an unreleased version it is said, and the
+      # starter lockfile and the packed smoke below (which makes a project) are skipped.
+      # Asked BEFORE packaging: the starter lockfile is made from it and packed.
+      - name: The engine the app pins is on npm
+        id: engine
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(node -p "require('./apps/desktop/package.json').version")"
+          missing=""
+          for name in @adminiumjs/adminium @adminiumjs/public-client; do
+            if ! npm view "${name}@${version}" version >/dev/null 2>&1; then missing="${missing} ${name}@${version}"; fi
+          done
+          if [ -z "${missing}" ]; then
+            echo "published=true" >> "$GITHUB_OUTPUT"
+            echo "On npm: @adminiumjs/adminium@${version} and @adminiumjs/public-client@${version}."
+          else
+            echo "published=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::Not on npm:${missing}. A project made in this build could not install its packages."
+            case "${GITHUB_REF}" in
+              refs/tags/desktop-v*) echo "::error::Publish the engine first: the desktop app is released only after the version it pins is on npm."; exit 1 ;;
+            esac
+          fi
+
+      # ── Step 3.6b: the starter lockfile, packed with the app ───────────────────
+      #
+      # What a new project installs is what this release was tried with, package
+      # by package: the lockfile is resolved here, once, and carried in the app
+      # (`resources/starter`, which is not in the repository). Without this step
+      # every packed app carries none and a new project resolves its ranges on
+      # the person's computer, on the day they click "Create".
+      - name: Make the starter lockfile
+        if: steps.engine.outputs.published == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          node scripts/release/starter-lockfile.mjs
+          test -s apps/desktop/resources/starter/starter-lock.json
+          test -s apps/desktop/resources/starter/starter.json
+
       # ── Step 3: package + (mac) sign + notarize ──────────────────────────────
       #
       # The `dist` script (= `electron-builder`) is the ONLY sanctioned call site
@@ -542,6 +587,50 @@ jobs:
       # rpm), the feed files, and .blockmaps into dist/. Ship the whole directory
       # to the release job; retention is short because these are release-candidate
       # binaries, not long-lived history (the published Release is the archive).
+      # ── Step 3.55: the entitlement a project's packages need, on the app AND its helper ──
+      #
+      # A project's own packages bring libraries signed by somebody else (SQLite,
+      # argon2, Tailwind's). The signed app loads them only with
+      # `disable-library-validation`, and the server runs in a HELPER, which has
+      # its own signature: the key on the app alone is a project that cannot start.
+      - name: The entitlement is on the app and on its helper (macOS)
+        if: matrix.platform == 'mac' && env.MAC_CSC_LINK != ''
+        shell: bash
+        run: |
+          set -euo pipefail
+          found=0
+          for app in apps/desktop/dist/mac*/Adminium.app; do
+            [ -d "$app" ] || continue
+            found=1
+            for signed in "$app" "$app"/Contents/Frameworks/*Helper*.app; do
+              [ -e "$signed" ] || continue
+              if ! codesign -d --entitlements - "$signed" 2>/dev/null | grep -q 'com.apple.security.cs.disable-library-validation'; then
+                echo "::error::$signed is signed without disable-library-validation: a project's packages would not load."
+                exit 1
+              fi
+              echo "ok: $signed"
+            done
+          done
+          [ "$found" = 1 ] || { echo "::error::no packed Adminium.app found to check"; exit 1; }
+
+      # ── Step 3.7: start the PACKED app and make a project in it ────────────────
+      #
+      # No other step runs what a person will run. This one starts the packed app
+      # (unpacked folder, the same files the installer lays down), makes a project
+      # (the engine's `new` run by the app's own program as Node, its packages
+      # fetched by the npm the app carries), runs one turn with a scripted model
+      # and checks the result. See scripts/release/desktop-packed-smoke.mjs.
+      - name: Packed smoke (make a project in the packed app)
+        if: steps.engine.outputs.published == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ "${{ matrix.platform }}" = "linux" ]; then
+            xvfb-run -a node scripts/release/desktop-packed-smoke.mjs
+          else
+            node scripts/release/desktop-packed-smoke.mjs
+          fi
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -55,3 +55,6 @@ scripts/release/out/
 # locks. Ignore the whole directory. Nothing here is shared today; add a negated
 # `!` line if a specific config ever needs to be committed.
 /.claude/
+
+# Made at release (scripts/release/starter-lockfile.mjs): the lockfile a new project starts with.
+apps/desktop/resources/starter/

README.md

@@ -38,6 +38,10 @@ React in `pages/` and `widgets/`.
 the encryption key for every stored DSN and API key. Generate it once with
 `openssl rand -hex 32`.
 
+**Desktop app** — macOS, Windows and Linux, with no Docker, Node or terminal:
+[adminium.dev/download](https://adminium.dev/download/#desktop)
+([what each installer is](https://docs.adminium.dev/desktop/)).
+
 **Docker Compose** — the reference deployment:
 
 ```sh

apps/dashboard/src/app/router.tsx

@@ -18,6 +18,8 @@ import {
   type RouterHistory,
 } from '@tanstack/react-router';
 import { allLocales, getI18nRevision, subscribeI18nRevision } from '@adminium/i18n';
+
+import { rememberInDesktopApp } from '../lib/desktop-runtime.js';
 import { ThemeProvider, TooltipProvider, type ThemePrefs } from '@adminium/ui';
 import { ChartDirectionBridge, WidgetRuntimeProvider } from '@adminium/widgets';
 
@@ -183,6 +185,9 @@ function RootComponent() {
           { globalDefaults: { locale: bootLocale() } }
         : { userPrefs: toThemePrefs(boot.data.prefs) })}
       onPrefChange={(key, value) => {
+        // In the desktop app the two the app's own screens share are kept by the app as well, so its first screen
+        // opens in the language and theme picked here. A pick only: nothing is written at boot.
+        rememberInDesktopApp(key, value);
         // Persist per-user axes once signed in (ThemeProvider wiring).
         if (!authed) return;
         api.patch('/api/v1/me/prefs', { [key]: value }).catch(() => {

apps/dashboard/src/designer/DesignBanners.tsx

@@ -27,6 +27,7 @@ import { Button, FormField, Input } from '@adminium/ui';
 import { ApiError } from '../app/api.js';
 import { designerApi, designerKeys, designerStateQuery, PREVIEW_USER_EMAIL } from './api.js';
 import { t } from '../i18n/t.js';
+import { getDesktopApi } from '../lib/desktop-runtime.js';
 import { useDesignerMessages } from './designerMessages.js';
 import { useAppToasts } from '../pages/toasts.js';
 
@@ -121,7 +122,9 @@ function OwnerPassword(): ReactNode {
       <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
         <KeyRound aria-hidden="true" className="size-4 shrink-0 text-accent" />
         <span className="min-w-0 flex-1">
-          {t('designer:banner.owner', 'You are this project’s owner, signed in by the link Adminium Designer printed. Set an address and a password before the project runs anywhere else.')}
+          {getDesktopApi() !== null
+            ? t('designer:banner.ownerApp', 'You are this project’s owner, signed in by the Adminium app on this computer. Set an address and a password before the project is shared or runs anywhere else.')
+            : t('designer:banner.owner', 'You are this project’s owner, signed in by the link Adminium Designer printed. Set an address and a password before the project runs anywhere else.')}
         </span>
         {open ? null : (
           <Button size="sm" onClick={() => setOpen(true)}>

apps/dashboard/src/designer/SpentLinkPage.tsx

@@ -10,7 +10,8 @@
  * shows commands elsewhere.
  */
 import { useState, type ReactNode } from 'react';
-import { Check, Copy, Hexagon, Link2Off } from 'lucide-react';
+import { Check, Copy, Link2Off } from 'lucide-react';
+import { AdminiumMark } from '@adminium/ui';
 
 import { t } from '../i18n/t.js';
 import { useDesignerMessages } from './designerMessages.js';
@@ -30,7 +31,7 @@ export function SpentLinkPage(): ReactNode {
     <main className="flex min-h-dvh flex-col items-center justify-center gap-6 bg-bg p-6 text-fg">
       <div className="flex items-center gap-2.5">
         <span className="flex size-7 items-center justify-center rounded-lg bg-accent text-accent-fg" aria-hidden="true">
-          <Hexagon className="size-4" />
+          <AdminiumMark className="size-[18px]" />
         </span>
         <span className="text-[15px] font-extrabold tracking-tight">{t('designer:brand', 'Adminium Designer')}</span>
       </div>

apps/dashboard/src/designer/api.ts

@@ -35,6 +35,8 @@ export interface DesignerState {
   active: { sessionId: string; turn: number } | null;
   /** The person asking is the owner `design` made, still with no password. */
   ownerNeedsPassword?: boolean;
+  /** Names in the project's `.env` the app did not obey (it decides them itself). */
+  ignoredEnv?: string[];
 }
 
 /** Who the preview signs in as: the dashboard says so when it is opened as them outside the Designer's frame. */
@@ -88,6 +90,10 @@ export interface DesignerModels {
   selected: { connectionId: string; model: string } | null;
   verdicts: { connectionId: string; model: string; canBuild: boolean; message: string | null }[];
   canAdd: boolean;
+  /** Inside the desktop app: where the app keeps keys (`null` and absent elsewhere: they are in the project's `.env`). */
+  kept?: 'key-store' | 'plain' | null;
+  /** Inside the desktop app: model names this project's `.env` sets, which are not used there. */
+  ignoredEnv?: string[];
 }
 
 export interface ConnectionDraft {
@@ -403,6 +409,8 @@ export const designerApi = {
   /** One of the app's files a person may open, whole, with the hash it has now. */
   fileContent: (id: string, path: string) => api.get<{ path: string; content: string; hash: string }>(`${BASE}/sessions/${id}/files/content?path=${encodeURIComponent(path)}`),
   previewTicket: (id: string, to: string) => api.post<{ url: string; origin: string; seenAs?: string[] }>(`${BASE}/sessions/${id}/preview-ticket`, { to }),
+  /** A one-use link that signs this project's local owner in from the system's browser, landing on `to` (a path). */
+  browserLink: (to: string) => api.post<{ data: { url: string } }>('/api/v1/auth/design-link', { to }),
   setOwnerPassword: (input: { email: string; password: string }) => api.post<{ email: string }>(`${BASE}/owner-password`, input),
   createSession: (input: { appKey?: string; name?: string; /** The session's title until the Designer names the app. */ title?: string; /** A style picked at the start. */ style?: string; target: DesignerTarget; connectionId: string; model: string; text?: string; /** With `text`: this page will show the preview and say what it sees. */ sees?: boolean }) =>
     api.post<{ session: DesignerSession; turn: number | null }>(`${BASE}/sessions`, input),

apps/dashboard/src/designer/build/BuildPage.tsx

@@ -47,7 +47,9 @@ import {
   StoppedNote,
   UsageLine,
 } from '../parts/chat.js';
+import { useDesktopVersions, VersionsOfferDialog } from '../parts/DesktopVersions.js';
 import { TopBar } from '../parts/TopBar.js';
+import { DesktopBuildShare } from '../parts/DesktopProject.js';
 import { CHAT_WIDTH, FOLDED_NEED_GUESS, views } from './barLevel.js';
 import { LeaveGuard } from './LeaveGuard.js';
 import { StyleMenu } from './LookMenu.js';
@@ -91,6 +93,12 @@ export function BuildPage({ sessionId }: { sessionId: string }): ReactNode {
   const session = useQuery(sessionQuery(sessionId));
   const apps = useQuery({ ...yourAppsQuery(), enabled: session.data !== undefined });
   const versions = useQuery({ ...versionsQuery(sessionId), enabled: session.data !== undefined });
+  // Inside the desktop app on a computer with no git: versions can be turned on without leaving the page.
+  const desktopVersions = useDesktopVersions(() => {
+    void queryClient.invalidateQueries({ queryKey: designerKeys.versions(sessionId) });
+    toasts.push({ variant: 'success', title: t('designer:versionsOffer.nowOn', 'Versions are on'), description: t('designer:versionsOffer.nowOnNext', 'Your next change is kept as a version.') });
+  });
+  const [offeringVersions, setOfferingVersions] = useState(false);
   const { events, loaded } = useSessionEvents(sessionId);
   const turns = useMemo(() => foldTurns(events), [events]);
   const working = isWorking(turns);
@@ -498,6 +506,7 @@ export function BuildPage({ sessionId }: { sessionId: string }): ReactNode {
 
   return (
     <div className="flex h-dvh flex-col bg-bg text-fg">
+      {desktopVersions === null ? null : <VersionsOfferDialog versions={desktopVersions} open={offeringVersions} onOpenChange={setOfferingVersions} />}
       <TopBar
         build
         middle={
@@ -510,6 +519,7 @@ export function BuildPage({ sessionId }: { sessionId: string }): ReactNode {
               current={current}
               busy={busy || working}
               onGoBack={(version) => restore.mutate({ n: version.n, record: true })}
+              onTurnVersionsOn={desktopVersions === null || desktopVersions.state.on ? undefined : () => setOfferingVersions(true)}
             />
           )
         }
@@ -525,6 +535,7 @@ export function BuildPage({ sessionId }: { sessionId: string }): ReactNode {
                 onOpen={(id) => void navigate({ to: '/design/$sessionId', params: { sessionId: id } })}
               />
             )}
+            <DesktopBuildShare />
             <a
               href="/"
               aria-label={t('designer:build.openDash', 'Open Dashboard')}

apps/dashboard/src/designer/build/MoreMenu.tsx

@@ -36,7 +36,8 @@ export function MoreMenu({
   seen: { label: string; tip: string } | null;
   sees: boolean;
   onSees: (on: boolean) => void;
-  onNewTab: () => void;
+  /** Absent where there is nowhere to open it. */
+  onNewTab?: (() => void) | undefined;
 }): ReactNode {
   const label = t('designer:preview.more', 'More');
   return (
@@ -82,7 +83,7 @@ export function MoreMenu({
         >
           {t('designer:preview.sees', 'The Designer looks at the page after it builds')}
         </DropdownMenuItem>
-        {rows ? (
+        {rows && onNewTab !== undefined ? (
           <DropdownMenuItem icon={<ExternalLink className="rtl:-scale-x-100" />} onSelect={onNewTab} className={MENU_ROW}>
             {t('designer:preview.newTab', 'Open in a new tab')}
           </DropdownMenuItem>

apps/dashboard/src/designer/build/Preview.tsx

@@ -120,7 +120,9 @@ export function Preview({ preview, session, turns, onFix, compact }: { preview:
       const sight = sightFrom(event.data, session.appKey);
       if (sight !== null) {
         // Once for each time the frame was opened, and never twice within two seconds: a screen that posts without end sends nothing more.
-        const due = sentSight.current.round !== round || Date.now() - sentSight.current.at > 2000;
+        // A sight that says the page stopped is passed on whenever it comes: it is the one the turn must not miss.
+        const stops = sight.faults.some((fault) => fault['kind'] === 'blank' || fault['kind'] === 'error');
+        const due = sentSight.current.round !== round || stops || Date.now() - sentSight.current.at > 2000;
         if (runningNow.current && seesPage() && due && sentSight.current.count < 3) {
           sentSight.current = { round, at: Date.now(), count: sentSight.current.round === round ? sentSight.current.count + 1 : 1 };
           void designerApi.sendSight(session.id, sight).catch(() => undefined);

apps/dashboard/src/designer/build/SessionTitle.tsx

@@ -23,6 +23,7 @@ import {
 import { getI18nInstance, t } from '../../i18n/t.js';
 import type { DesignerVersion } from '../api.js';
 import { editedWhen } from '../home/YourApps.js';
+import { VERSIONS_PILL } from '../parts/DesktopVersions.js';
 import { MENU_HEADING } from './MoreMenu.js';
 import { versionLabel, versionName } from './versionName.js';
 
@@ -63,6 +64,7 @@ export function SessionTitle({
   current,
   onGoBack,
   busy,
+  onTurnVersionsOn,
 }: {
   title: string;
   onRename: (title: string) => void;
@@ -71,6 +73,8 @@ export function SessionTitle({
   current: DesignerVersion | null;
   onGoBack: (version: DesignerVersion) => void;
   busy: boolean;
+  /** Inside the desktop app, on a computer with no git: versions can be turned on from here. */
+  onTurnVersionsOn?: (() => void) | undefined;
 }): ReactNode {
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState(title);
@@ -130,7 +134,30 @@ export function SessionTitle({
         </Tooltip>
       )}
 
-      {!available ? (
+      {!available && onTurnVersionsOn !== undefined ? (
+        <DropdownMenu modal={false}>
+          <DropdownMenuTrigger
+            aria-label={t('designer:versionsOffer.offButton', 'Versions: off')}
+            className="inline-flex h-8 shrink-0 items-center gap-1.5 whitespace-nowrap rounded-[9px] border border-border bg-surface-2 pe-[7px] ps-[9px] text-[12.5px] font-bold leading-[normal] text-fg hover:border-border-strong focus-visible:outline-2 focus-visible:outline-accent"
+          >
+            <History aria-hidden="true" className="size-3.5 text-fg-subtle" />
+            <span className="text-fg-muted">{t('designer:versionsOffer.offWord', 'Off')}</span>
+            <ChevronDown aria-hidden="true" className="size-3.5 text-fg-subtle" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="center" className="w-[420px] max-w-[calc(100vw-24px)] rounded-[14px] p-1.5 leading-[normal]">
+            <DropdownMenuLabel className={MENU_HEADING}>{t('designer:versions.title', 'Versions')}</DropdownMenuLabel>
+            <div className="flex flex-col items-center gap-3 px-4 pb-5 pt-[22px] text-center">
+              <span aria-hidden="true" className="flex size-10 items-center justify-center rounded-[12px] bg-surface-3 text-fg-muted">
+                <History className="size-[19px]" />
+              </span>
+              <span className="text-[13px] text-fg-muted">{t('designer:versionsOffer.offHere', 'Versions are off on this computer.')}</span>
+              <DropdownMenuItem onSelect={onTurnVersionsOn} icon={<History />} className={`${VERSIONS_PILL} w-auto [&_svg]:size-3.5`}>
+                {t('designer:versionsOffer.turnOn', 'Turn versions on')}
+              </DropdownMenuItem>
+            </div>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : !available ? (
         <Tooltip content={t('designer:versions.offHint', 'Versions need git on this machine. Install git and start the Designer again.')}>
           <span tabIndex={0} className="inline-flex items-center gap-1.5 rounded-lg px-2 py-1 text-xs font-semibold text-fg-subtle">
             <History aria-hidden="true" className="size-3.5" />