@hienlh/ppm 0.23.10 → 0.23.11

package/src/shared/design-skill-mentions.ts

@@ -0,0 +1,112 @@
+/**
+ * Skills named inside the user's design instructions (Settings → Design).
+ *
+ * The instructions are one global text, but a skill is only real for the runtime that
+ * loads it: a Claude session resolves `/ak:ui-ux-pro-max` through its plugin registry, a
+ * Codex session through `skills/list`. So a mention is parsed here once, provider-neutral,
+ * and resolved separately against each runtime's own list. Shared by the server (which
+ * turns a resolved mention into a directive) and the settings pane (which shows which
+ * mentions resolve where), so the two can never disagree about what counts as a mention.
+ */
+
+/** What a mention is resolved against: a slash item's name plus the aliases discovery kept. */
+export interface SkillCandidate {
+  name: string;
+  aliases?: string[];
+}
+
+export interface MentionResolution<T extends SkillCandidate = SkillCandidate> {
+  resolved: Array<{ mention: string; skill: T }>;
+  unresolved: string[];
+}
+
+/** More than this is not a design method any more, and each one costs a directive line. */
+export const MAX_SKILL_MENTIONS = 16;
+
+export const DESIGN_INSTRUCTIONS_MAX_BYTES = 8 * 1024;
+
+/**
+ * A mention opens a word — start of text, whitespace or an opening bracket or quote — with
+ * `/` (every picker in PPM) or `$` (what codex itself uses and what the picker inserts for a
+ * codex skill). Requiring the word boundary keeps a path like `src/app` or the `/pricing` of
+ * a URL from counting. Names start with a lowercase letter, as skill names do by
+ * convention, which also keeps shell variables (`$HOME`) and prices (`$29/mo`) out. A page
+ * route such as `/pricing` still looks like a mention; the prompt says to read an
+ * unresolved one as ordinary text.
+ */
+const MENTION_RE = /(^|[\s([{"'`])[/$]([a-z][a-z0-9._-]*(?::[a-z0-9._-]+)*(?:\/[a-z0-9._-]+)*)/g;
+
+/** Sentence punctuation that the name pattern accepts but no name ends with. */
+const TRAILING_PUNCTUATION_RE = /[._:-]+$/;
+
+/** The mentioned names in order of first appearance, without their sigil, deduplicated. */
+export function extractSkillMentions(text: string): string[] {
+  const seen = new Set<string>();
+  for (const match of text.matchAll(MENTION_RE)) {
+    const name = (match[2] ?? "").replace(TRAILING_PUNCTUATION_RE, "");
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    if (seen.size >= MAX_SKILL_MENTIONS) break;
+  }
+  return [...seen];
+}
+
+/** The part after a plugin or kit namespace: `ak-engineer:ak-debug` → `ak-debug`. */
+function baseName(name: string): string {
+  const colon = name.lastIndexOf(":");
+  return colon === -1 ? name : name.slice(colon + 1);
+}
+
+/**
+ * The installed skill a mention means, or null.
+ *
+ * Exact name first, then an alias (AgentKit's declared `ak:debug` for the registered
+ * `ak-engineer:ak-debug`), then the un-namespaced name — which is what lets one global
+ * text written as `/ak:ui-ux-pro-max` also find a codex skill registered as plain
+ * `ui-ux-pro-max`, and the reverse. The first match wins, following discovery order, the
+ * same rule the chat composer applies to a typed alias.
+ */
+export function resolveSkillMention<T extends SkillCandidate>(mention: string, candidates: readonly T[]): T | null {
+  const exact = candidates.find((c) => c.name === mention);
+  if (exact) return exact;
+  const alias = candidates.find((c) => c.aliases?.includes(mention));
+  if (alias) return alias;
+  const base = baseName(mention);
+  return candidates.find((c) => baseName(c.name) === base || c.aliases?.some((a) => baseName(a) === base)) ?? null;
+}
+
+export function resolveSkillMentions<T extends SkillCandidate>(
+  mentions: readonly string[],
+  candidates: readonly T[],
+): MentionResolution<T> {
+  const resolved: MentionResolution<T>["resolved"] = [];
+  const unresolved: string[] = [];
+  for (const mention of mentions) {
+    const skill = resolveSkillMention(mention, candidates);
+    if (skill) resolved.push({ mention, skill });
+    else unresolved.push(mention);
+  }
+  return { resolved, unresolved };
+}
+
+/** UTF-8 size, which is what the cap is about: the text ends up in every design prompt. */
+export function utf8ByteLength(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+export type NormalizedInstructions = { ok: true; text: string } | { ok: false; error: string };
+
+/**
+ * Validate a submitted instructions text. Line endings are folded to LF and the ends
+ * trimmed, so a text saved from Windows and one saved from a phone compare equal; a NUL
+ * is refused rather than stripped because no editor produces one.
+ */
+export function normalizeDesignInstructions(value: unknown): NormalizedInstructions {
+  if (typeof value !== "string") return { ok: false, error: "instructions must be a string" };
+  if (value.includes("\u0000")) return { ok: false, error: "instructions must not contain NUL characters" };
+  const text = value.replace(/\r\n?/g, "\n").trim();
+  if (utf8ByteLength(text) > DESIGN_INSTRUCTIONS_MAX_BYTES) {
+    return { ok: false, error: `instructions must be ${DESIGN_INSTRUCTIONS_MAX_BYTES / 1024} KB or less` };
+  }
+  return { ok: true, text };
+}

package/src/shared/design-skill-suggestion.ts

@@ -0,0 +1,50 @@
+import {
+  extractSkillMentions, resolveSkillMentions, type SkillCandidate,
+} from "./design-skill-mentions";
+
+/**
+ * The design skill PPM points to when a machine has none. PPM never installs it: the
+ * commands are shown for the user to run, copied from the upstream README
+ * (github.com/nextlevelbuilder/ui-ux-pro-max-skill, MIT) rather than invented here.
+ */
+export const DESIGN_SKILL_SUGGESTION = {
+  name: "ui-ux-pro-max",
+  repoUrl: "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill",
+  license: "MIT",
+  requirement: "Its search scripts need Python 3.",
+  installs: [
+    {
+      label: "Claude Code, inside a Claude Code session",
+      lines: [
+        "/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill",
+        "/plugin install ui-ux-pro-max@ui-ux-pro-max-skill",
+      ],
+    },
+    {
+      label: "Claude Code, from a terminal (all projects)",
+      lines: ["npm install -g ui-ux-pro-max-cli", "uipro init --ai claude --global"],
+    },
+    {
+      label: "Codex, from the project folder",
+      lines: ["npm install -g ui-ux-pro-max-cli", "uipro init --ai codex"],
+    },
+  ],
+} as const;
+
+/** Installed copies go by several names (`ui-ux-pro-max`, AgentKit's `ak:ui-ux-pro-max`). */
+const KNOWN_DESIGN_SKILL_RE = /ui-ux-pro-max/i;
+
+export function isKnownDesignSkill(skill: SkillCandidate): boolean {
+  return KNOWN_DESIGN_SKILL_RE.test(skill.name) || !!skill.aliases?.some((a) => KNOWN_DESIGN_SKILL_RE.test(a));
+}
+
+/**
+ * Whether to suggest installing a design skill: nothing the instructions name resolves
+ * for any provider, and no known design skill is installed for any of them. One provider
+ * having it is enough — the user is then already set up, whichever provider they design on.
+ */
+export function needsDesignSkillSuggestion(instructions: string, skillLists: ReadonlyArray<readonly SkillCandidate[]>): boolean {
+  const mentions = extractSkillMentions(instructions);
+  return !skillLists.some((skills) =>
+    skills.some(isKnownDesignSkill) || resolveSkillMentions(mentions, skills).resolved.length > 0);
+}

package/src/shared/design-system-init-prompt.ts

@@ -1,21 +1,52 @@
 /**
- * The message that sets up a project's design system, placed in the design chat's composer
- * for the user to review and send (never sent automatically).
+ * The message that sets up one app's design system, sent (auto-sent, since the user clicked
+ * a button asking for exactly this) into that app's showcase design chat.
  *
- * It asks for one read of the codebase and exactly two files, `designs/DESIGN.md` and
- * `designs/tokens.css`, which every design session is told to follow and link. Writing
- * anything else is ruled out explicitly, because this runs in a design session whose
- * permission default auto-approves file edits inside the project.
+ * It asks for one read of the app's own codebase and a fixed set of files under
+ * `designs/systems/<id>/` (the legacy `designs/` root for the implicit `default` app) —
+ * `DESIGN.md`, `tokens.css` and the `kit/` folder — which every design of this app is told
+ * to follow and link, plus the app's showcase page at `designs/system-<id>/index.html`. The
+ * kit is the app's *real* compiled CSS (not a Tailwind CDN runtime) when it has one, or, for
+ * a CSS-in-JS stack, built from its theme sources instead — so a design that links it
+ * reproduces the app's actual class names and markup, or its real component recipes, 1:1.
+ * Writing anything outside those folders is ruled out explicitly, because this runs in a
+ * design session whose permission default auto-approves file edits inside the project —
+ * running the app's own build (or reading its existing output) is fine, changing its source
+ * is not, and `.env*` contents are never read.
  */
-export function buildDesignSystemInitPrompt(): string {
-  return `Set up this project's design system so every design here matches the product.
 
-1. Read the codebase once to learn its visual language: global stylesheets, theme and token
-   files (CSS custom properties, Tailwind config, theme objects), the font setup, and a few
-   of the most used UI components (buttons, inputs, cards, navigation). Skip dependencies,
-   build output and generated files.
+export interface DesignSystemInitTarget {
+  id: string;
+  label: string;
+  /** Relative to the project root; `.` for the project itself. */
+  root: string;
+  platform: "web" | "mobile";
+}
+
+const DEFAULT_SYSTEM_ID = "default";
+
+export function buildDesignSystemInitPrompt(target: DesignSystemInitTarget): string {
+  const appRef = target.root === "." ? "this project" : `\`${target.root}/\` in this project`;
+  const outDir = target.id === DEFAULT_SYSTEM_ID ? "designs/" : `designs/systems/${target.id}/`;
+  const showcaseDir = `designs/system-${target.id}/`;
+  const previewPrefix = `../systems/${target.id}`;
+  const cssInJsNote = "If it is styled with CSS-in-JS (MUI, antd v5, styled-components, emotion) rather than a "
+    + "compiled stylesheet, build `kit/app.css` from its theme sources instead (theme objects, antd tokens / "
+    + "`ConfigProvider`, MUI `createTheme`), and in the component map name the library component each kit recipe "
+    + "stands for (e.g. antd `<Button type=\"primary\">`), so a later code agent can map a recipe back to it.";
+  const mobileNote = target.platform === "mobile"
+    ? "This app is mobile (React Native or similar): make the tokens and recipes emulate its native components "
+      + "rather than HTML form controls, and build the showcase page to be viewed in the phone frame."
+    : "";
+
+  return `Set up the design system for "${target.label}" (${appRef}) so every design for this app matches it.
+
+1. Read ${appRef}'s codebase once to learn its visual language: global stylesheets, theme and
+   token files (CSS custom properties, Tailwind config, theme objects), the font setup, and a
+   few of the most used UI components (buttons, inputs, cards, navigation). Skip dependencies,
+   build output and generated files. Never read \`.env*\` file contents.
 
-2. Write \`designs/DESIGN.md\`, a concise guide for designing screens for this product:
+2. Write \`${outDir}DESIGN.md\`, a concise guide for designing screens for this app:
    - brand character and tone in a few sentences;
    - the colour palette with roles (background, surface, text, muted text, accent, border,
      success, warning, danger), each with its value, for light and dark mode if both exist;
@@ -24,12 +55,36 @@ export function buildDesignSystemInitPrompt(): string {
    - the look of the core components, with the class names or markup patterns the code uses;
    - layout conventions (widths, grids, breakpoints) and any do's and don'ts you noticed.
 
-3. Write \`designs/tokens.css\` with a single \`:root { ... }\` block declaring those values as
+3. Write \`${outDir}tokens.css\` with a single \`:root { ... }\` block declaring those values as
    CSS custom properties with clear names (\`--color-accent\`, \`--radius-md\`, \`--space-4\`,
-   \`--font-body\`...), plus a \`@media (prefers-color-scheme: dark)\` block if the product
-   has a dark theme. Plain CSS only: no imports, no build step, no framework syntax.
+   \`--font-body\`...), plus a \`@media (prefers-color-scheme: dark)\` block if the app has a
+   dark theme. Plain CSS only: no imports, no build step, no framework syntax.
+
+4. Build the app (or find its existing build output) and copy its real, compiled CSS into
+   \`${outDir}kit/app.css\`. Rewrite any \`url(...)\` it uses for fonts to point at files you copy
+   alongside it under \`${outDir}kit/fonts/\`. If the app has no CSS build step at all,
+   hand-assemble \`${outDir}kit/app.css\` from its real stylesheets instead — it must still be
+   the actual rules the app uses, not a guess. ${cssInJsNote} Prefer an existing build output
+   or a build that needs no env file, and ask me before running one that needs secrets. Never
+   edit the app's own source or build output; only read it and copy files into \`${outDir}kit/\`.
+
+5. Extract the icons the app actually uses (as real SVG artwork, one file per icon) into
+   \`${outDir}kit/icons/<name>.svg\`.
+
+6. Add a \`## Screens and components\` section to \`${outDir}DESIGN.md\`: for each of the app's
+   main screens and reusable components, list its source file path(s) and a short markup
+   snippet using the real class names and icons from the kit, so a design session can find
+   and reproduce it faithfully.
+
+7. Build the showcase page at \`${showcaseDir}index.html\`: link it with
+   \`<link rel="stylesheet" href="${previewPrefix}/tokens.css">\` and, if you built one,
+   \`<link rel="stylesheet" href="${previewPrefix}/kit/app.css">\`, then lay out the colour
+   palette, the type scale, the spacing scale, and a handful of the app's main screens or components
+   reproduced with the kit, so I can judge how well it matches at a glance. ${mobileNote}
 
 Take the values from the code rather than inventing them, and say where you are unsure.
-Create or change only those two files: do not modify any other file in the project, and do
-not create a design folder.`;
+Create or change only \`${outDir}DESIGN.md\`, \`${outDir}tokens.css\`, files under
+\`${outDir}kit/\`, and \`${showcaseDir}\`: do not modify any other file in the project,
+especially not ${appRef}'s own source. Running this again replaces what it already produced;
+nothing here re-syncs on its own.`;
 }

package/src/shared/design-types.ts

@@ -7,6 +7,8 @@
  * design sessions carry `designs/<slug>/` in their instructions.
  */
 
+import type { DesignVariant } from "./design-variants";
+
 /** `slides` is a deck of 1280x720 sections; `page` is a single page or prototype. */
 export const DESIGN_KINDS = ["page", "slides"] as const;
 export type DesignKind = (typeof DESIGN_KINDS)[number];
@@ -21,9 +23,20 @@ export interface DesignSummary {
   kind: DesignKind;
   /** Entry HTML file, relative to the design folder. */
   entry: string;
+  /**
+   * The variants the canvas can switch between, variant 1 (the entry) first, only files that
+   * exist. Absent from an older server, which means the entry alone (`designVariantsOf`).
+   */
+  variants?: DesignVariant[];
+  /** Why entries of `design.json`'s `variants` were skipped; absent when none were. */
+  variantWarnings?: string[];
   createdAt: string;
   /** Latest of the manifest's own timestamp and the entry file's mtime, ISO. */
   updatedAt: string;
+  /** The app this design belongs to; `"default"` when the manifest names none. */
+  system: string;
+  /** Set when this design is an app's showcase (`designs/system-<id>/`); the app's id. */
+  showcaseFor?: string;
 }
 
 /**
@@ -46,10 +59,46 @@ export interface DesignSnapshotInfo {
   treeHash: string;
 }
 
-/** Whether the project-level design system files exist (`designs/DESIGN.md`, `designs/tokens.css`). */
-export interface DesignSystemStatus {
-  designMd: boolean;
-  tokensCss: boolean;
+/**
+ * An "app" of the project: one declared design system under `designs/systems/<id>/`, or the
+ * implicit `default` app backed by the legacy `designs/DESIGN.md` + `designs/tokens.css` +
+ * `designs/kit/` (never moved). `root` is relative to the project root (`.` for the project
+ * itself); `platform` decides whether the showcase and a design built for this app render in
+ * a phone frame with native-looking components.
+ */
+export const DESIGN_PLATFORMS = ["web", "mobile"] as const;
+export type DesignPlatform = (typeof DESIGN_PLATFORMS)[number];
+
+export function isDesignPlatform(value: unknown): value is DesignPlatform {
+  return typeof value === "string" && (DESIGN_PLATFORMS as readonly string[]).includes(value);
+}
+
+export interface DesignSystemBuiltFrom {
+  /** `git rev-parse HEAD` of the app root at the moment a setup turn last finished. */
+  commit: string;
+  at: string;
+}
+
+export interface DesignSystemSummary {
+  id: string;
+  label: string;
+  /** Relative to the project root; `.` for the project itself. */
+  root: string;
+  platform: DesignPlatform;
+  /** True when `designs/systems/<id>/system.json` exists; false for the unreleased implicit default. */
+  declared: boolean;
+  builtFrom?: DesignSystemBuiltFrom;
+  hasDesignMd: boolean;
+  hasTokensCss: boolean;
+}
+
+/** Server-computed, cached per (root, HEAD); never blocks the designs list. */
+export interface DesignSystemStaleInfo {
+  stale: boolean;
+  /** Files changed since `builtFrom.commit`, restricted to the app root. Present when known. */
+  changedFiles?: number;
+  /** True when there is no repo, no `builtFrom`, or the check timed out — "unknown", not stale. */
+  unknown: boolean;
 }
 
 /** `YYYYMMDD-HHMMSS-xxxx` (UTC time + 4 hex). Checked after URL decoding, before any path use. */

package/src/shared/design-variants.ts

@@ -0,0 +1,101 @@
+/**
+ * Design variants: alternative directions for one brief, one HTML file each, that the canvas
+ * switches between. `design.json` lists them as `variants: [{ file, label }]`, variant 1
+ * being the design's entry page.
+ *
+ * The list is written by the agent, so it is parsed tolerantly: every bad entry is dropped
+ * with a warning the canvas shows, and whatever survives is still a usable list whose first
+ * item is the entry. A missing list is just the entry, which is also what an older build that
+ * ignores the field shows.
+ */
+
+export const MAX_DESIGN_VARIANTS = 5;
+export const MAX_VARIANT_LABEL = 40;
+
+export interface DesignVariant {
+  /** A plain file name in the design folder, e.g. `variant-2.html`. */
+  file: string;
+  /** Short name of the direction; empty when the agent gave none. */
+  label: string;
+}
+
+export interface ParsedVariants {
+  variants: DesignVariant[];
+  warnings: string[];
+}
+
+/**
+ * A top-level HTML file: no directories, no leading dot (that would reach `.design/`). Kept
+ * flat so the chosen variant can take the entry's place without its relative links moving.
+ */
+const VARIANT_FILE_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}\.html?$/i;
+
+export function isVariantFileName(value: unknown): value is string {
+  return typeof value === "string" && VARIANT_FILE_RE.test(value);
+}
+
+/** Trimmed, control characters removed, at most {@link MAX_VARIANT_LABEL} characters. */
+export function normalizeVariantLabel(value: unknown): string {
+  if (typeof value !== "string") return "";
+  const flat = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  return Array.from(flat).slice(0, MAX_VARIANT_LABEL).join("");
+}
+
+/** A file name as it may appear in a warning: the agent wrote it, so it is cut short. */
+const shown = (value: unknown): string =>
+  (typeof value === "string" ? value : String(value)).replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 60);
+
+/** Case-folded, because Windows and macOS treat `Variant-2.html` and `variant-2.html` as one file. */
+const sameFile = (a: string, b: string): boolean => a.toLowerCase() === b.toLowerCase();
+
+export function parseDesignVariants(value: unknown, entry: string): ParsedVariants {
+  const warnings: string[] = [];
+  const entryItem = (label = ""): DesignVariant => ({ file: entry, label });
+  if (value === undefined || value === null) return { variants: [entryItem()], warnings };
+  if (!Array.isArray(value)) {
+    return { variants: [entryItem()], warnings: ["`variants` in design.json is not a list, so only the entry page is shown."] };
+  }
+  if (entry.includes("/")) {
+    return { variants: [entryItem()], warnings: ["Variants need the entry page at the top of the design folder, so only the entry page is shown."] };
+  }
+
+  const list: DesignVariant[] = [];
+  value.forEach((raw: unknown, i) => {
+    const file = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>).file : undefined;
+    if (typeof file !== "string" || !file) {
+      warnings.push(`Variant ${i + 1} in design.json has no file name and was skipped.`);
+    } else if (!isVariantFileName(file)) {
+      warnings.push(`"${shown(file)}" is not an HTML file at the top of the design folder and was skipped.`);
+    } else if (list.some((v) => sameFile(v.file, file))) {
+      warnings.push(`${shown(file)} is listed twice in design.json; the second entry was skipped.`);
+    } else {
+      list.push({ file, label: normalizeVariantLabel((raw as Record<string, unknown>).label) });
+    }
+  });
+
+  const at = list.findIndex((v) => sameFile(v.file, entry));
+  if (at === -1) {
+    if (list.length > 0) warnings.push(`Variant 1 must be the entry page ${shown(entry)}; it was added in front.`);
+    list.unshift(entryItem());
+  } else if (at > 0) {
+    warnings.push(`Variant 1 must be the entry page ${shown(entry)}; it was moved in front.`);
+    list.unshift(...list.splice(at, 1));
+  }
+  // The entry keeps the manifest's spelling of its name, whatever case the list used.
+  list[0] = { file: entry, label: list[0]!.label };
+  if (list.length > MAX_DESIGN_VARIANTS) {
+    warnings.push(`design.json lists ${list.length} variants; only the first ${MAX_DESIGN_VARIANTS} are shown.`);
+    list.length = MAX_DESIGN_VARIANTS;
+  }
+  return { variants: list, warnings };
+}
+
+/** The variants of a design summary; an older server sends none, which means the entry alone. */
+export function designVariantsOf(design: { entry: string; variants?: DesignVariant[] }): DesignVariant[] {
+  return design.variants && design.variants.length > 0 ? design.variants : [{ file: design.entry, label: "" }];
+}
+
+/** "2 · Bold", or "Variant 2" when the agent gave the direction no name. */
+export function variantDisplayName(variant: DesignVariant, index: number): string {
+  return variant.label ? `${index + 1} · ${variant.label}` : `Variant ${index + 1}`;
+}

package/src/types/chat.ts

@@ -83,8 +83,9 @@ export interface AIProvider {
    * Skills the provider's own runtime would resolve for this session, for
    * providers that own a skill system PPM cannot read off disk. Implemented by
    * codex; absent for Claude, whose skills come from the shared disk discovery.
+   * `cwd` stands in for a session's project when there is no session yet.
    */
-  listSkills?(sessionId?: string): Promise<import("../providers/codex-app-server/codex-protocol").CodexSkill[]>;
+  listSkills?(sessionId?: string, cwd?: string): Promise<import("../providers/codex-app-server/codex-protocol").CodexSkill[]>;
   /** Drop runtime skill discovery results after a user requests a refresh. */
   invalidateSkillsCache?(): void;
   /** Provider-specific usage/quota (rate limits). Used by GET /chat/usage. */

package/src/types/system-hardware.ts

@@ -80,10 +80,16 @@ export interface CpuInfo {
    *  (Intel P+E) the physical count is what the kernel reports per socket. */
   physicalCores: number;
   logicalCores: number;
+  /** How the physical cores split on a part with two kinds — Apple Silicon's
+   *  performance and efficiency clusters. Both absent on a uniform CPU, and
+   *  where the host does not say. */
+  performanceCores?: number;
+  efficiencyCores?: number;
   /** Nominal clock and the highest the driver will ask for, MHz. */
   baseMHz?: number;
   maxMHz?: number;
-  /** "Intel VT-x" / "AMD-V", absent when the flag is missing (or hidden in a VM). */
+  /** "Intel VT-x" / "AMD-V" / "Apple Hypervisor", absent when the flag is missing
+   *  (or hidden in a VM). */
   virtualization?: string;
   /** True when this kernel is itself running virtualised. */
   isVirtualMachine: boolean;
@@ -118,6 +124,9 @@ export interface MemoryInfo {
   /** Populated slots. Empty when the firmware table is unreadable — the UI then
    *  shows the totals only, as Mission Center does inside a VM. */
   devices: MemoryDeviceInfo[];
+  /** Apple Silicon: the memory is inside the chip package. `devices` then holds
+   *  one entry for all of it, and there are no slots to count or fill. */
+  unified?: boolean;
   /** Slots the board has in total, when the firmware says. */
   slotsTotal?: number;
   /** Largest configuration the board accepts, bytes. */

package/src/types/system-metrics.ts

@@ -40,12 +40,17 @@ export interface MemoryMetrics {
   availableMB: number;
   /** usedMB / totalMB × 100. */
   percent: number;
-  /** Mission Center's composition bar, in BYTES. The four add up to the total, so
-   *  the bar needs no normalisation. Absent on a host with no /proc/meminfo. */
+  /** Mission Center's composition bar, in BYTES. On Linux the four add up to the
+   *  total. On darwin there is no `modifiedBytes` and the other three add up to
+   *  about the USABLE memory — the few hundred MB the firmware reserves are in
+   *  no page state — so the bar draws them against their own sum. Absent on a
+   *  host that publishes no page counts (Windows). */
   inUseBytes?: number;
-  /** Written-to pages not yet on disk (Dirty + Writeback). */
+  /** Written-to pages not yet on disk (Dirty + Writeback). Linux only: macOS
+   *  publishes no dirty-page count, and 0 would be a claim. */
   modifiedBytes?: number;
-  /** Reclaimable: page cache, buffers and reclaimable slab. */
+  /** Reclaimable: page cache, buffers and reclaimable slab. On darwin, Activity
+   *  Monitor's "Cached Files" (file-backed + purgeable pages). */
   standbyBytes?: number;
   freeBytes?: number;
   cachedMB?: number;
@@ -54,7 +59,8 @@ export interface MemoryMetrics {
   commitLimitMB?: number;
   swapTotalMB?: number;
   swapUsedMB?: number;
-  /** zram, summed across every device. `compressedMB` is what the compressed
+  /** zram, summed across every device — or on darwin the memory compressor, which
+   *  is the same idea built into the kernel. `compressedMB` is what the compressed
    *  pages occupy; `savingsMB` is what they would have occupied uncompressed
    *  minus that, i.e. the RAM the compression bought back. Both absent on a host
    *  with no zram — which is not the same as a host whose zram is empty. */
@@ -65,7 +71,8 @@ export interface MemoryMetrics {
 /** One fan, plus the temperature its chip reports beside it — Mission Center's
  *  Fan page. Small and few, so the labels ride the tick rather than the inventory. */
 export interface FanMetrics {
-  /** Stable across ticks: "<hwmon name>/fan<N>", e.g. "it8689/fan1". */
+  /** Stable across ticks: "<hwmon name>/fan<N>", e.g. "it8689/fan1", or
+   *  "smc/fan<N>" on a Mac. */
   id: string;
   /** The chip's own label when it has one, else "Fan N". */
   label: string;
@@ -75,6 +82,9 @@ export interface FanMetrics {
   /** The chip's temperature sensor with the same index, °C. */
   tempC?: number;
   tempName?: string;
+  /** The speeds the fan controller keeps it between (a Mac's SMC). */
+  minRpm?: number;
+  maxRpm?: number;
 }
 
 /** Whole-machine throughput, bytes/second over the last tick. */
@@ -138,6 +148,10 @@ export interface GpuInfo {
   pcieMaxLanes?: number;
   /** One combined video engine (Intel VCS): the UI shows "Video encode/decode". */
   encodeDecodeShared?: boolean;
+  /** GPU cores, as the driver counts them (Apple GPUs: 32 on an M1 Max). */
+  coreCount?: number;
+  /** Highest Metal the GPU supports, "Metal 3". macOS only. */
+  metalVersion?: string;
 }
 
 export interface SystemMetrics {
@@ -226,8 +240,10 @@ export interface ProcessInfo {
   swapMB?: number;
   /** `"<scope>:<unit>"` — the Services row this pid belongs to, read from its
    *  cgroup ("system:sshd.service"). The scope is part of the key because
-   *  `dbus-broker.service` exists in BOTH on an ordinary desktop. Absent on a
-   *  host with no systemd, for a pid in no unit, and for another user's units.
+   *  `dbus-broker.service` exists in BOTH on an ordinary desktop. On macOS the
+   *  launchd job whose process this is or descends from ("user:com.example.agent"),
+   *  known only while the Services page is polling. Absent on a host with neither
+   *  manager, for a pid in no unit or job, and for another user's units.
    *  The Services page's live figures are summed over it. */
   unitKey?: string;
   /** Epoch ms UTC; 0 when unknown. Identity guard for CPU deltas, grouping and kill. */
@@ -289,6 +305,10 @@ export interface ProcessGroup {
 export interface ProcessColumnAvailability {
   disk: boolean;
   gpu: boolean;
+  /** False where the GPU column has no per-process memory to pair with its
+   *  percentage — macOS, whose GPU shares RAM and reports nobody's share of it —
+   *  so the cell shows the percentage alone. Absent = it has one. */
+  gpuMemory?: boolean;
   net: boolean;
   /** Linux only so far: `VmSwap` in `/proc/<pid>/status`. */
   swap: boolean;
@@ -396,15 +416,19 @@ export interface ProcessDetails {
   cgroup: string | null;
 }
 
-/** A running desktop application — Mission Center's "Apps" section. Linux only:
- *  identified from the user's app cgroups and `.desktop` Exec matching. */
+/** A running desktop application — Mission Center's "Apps" section. On Linux it is
+ *  found from the user's app cgroups and `.desktop` Exec matching; on macOS it is
+ *  the application bundle a process runs from. */
 export interface AppInfo {
-  /** Desktop file id without `.desktop`: "org.kde.konsole". Stable across ticks. */
+  /** Stable across ticks. Linux: the desktop file id without `.desktop`
+   *  ("org.kde.konsole"). macOS: CFBundleIdentifier ("com.google.Chrome"). */
   id: string;
-  /** The entry's unlocalised `Name=`. */
+  /** Linux: the entry's unlocalised `Name=`. macOS: CFBundleDisplayName, else
+   *  CFBundleName, else the bundle's folder name. */
   name: string;
-  /** The entry's `Icon=`: a theme icon name or an absolute path; resolved to an
-   *  image by `/api/system/app-icon`. Null when the entry has none. */
+  /** Linux: the entry's `Icon=`, a theme icon name or an absolute path. macOS: the
+   *  bundle's icon file name ("AppIcon.icns"). Either way `/api/system/app-icon`
+   *  resolves it to an image; null when the app declares none. */
   icon: string | null;
   /** Primary pids: app pids whose parent is not also one of this app's pids. Each
    *  stands for its whole subtree, which is what an app row's figures sum over. */