Add iOS New Thread home screen widget

apps/mobile/app.config.ts

@@ -181,6 +181,32 @@ const config: ExpoConfig = {
             description: "Shows the current state of active T3 Code agents.",
             supportedFamilies: ["systemSmall", "systemMedium", "accessoryRectangular"],
           },
+          {
+            name: "NewThread",
+            displayName: "New Thread",
+            description: "Start a new T3 Code thread right from your Home Screen.",
+            supportedFamilies: ["systemSmall", "systemMedium", "systemLarge"],
+            // Per-instance options in the long-press "Edit Widget" sheet. Enum
+            // parameters are compiled into Swift at prebuild, so the dynamic
+            // project list cannot be offered as a picker — pins are typed as
+            // text and matched against the synced projects inside the widget.
+            configuration: {
+              title: "New Thread",
+              description: "Pin specific projects; the rest fills with your latest activity.",
+              parameters: {
+                pinnedProjects: {
+                  title: "Pinned projects (comma-separated)",
+                  type: "string",
+                  default: "",
+                },
+                showRecent: {
+                  title: "Fill with recent projects",
+                  type: "boolean",
+                  default: true,
+                },
+              },
+            },
+          },
         ],
       },
     ],

apps/mobile/src/Stack.tsx

@@ -40,6 +40,7 @@ import { AddProjectSourceRoute } from "./features/projects/AddProjectSourceRoute
 import { NewTaskDraftRouteScreen } from "./features/threads/NewTaskDraftRouteScreen";
 import { NewTaskFlowProvider } from "./features/threads/new-task-flow-provider";
 import { NewTaskRouteScreen } from "./features/threads/NewTaskRouteScreen";
+import { useNewThreadWidgetSync } from "./features/threads/use-new-thread-widget-sync";
 import { SettingsAppearanceRouteScreen } from "./features/settings/SettingsAppearanceRouteScreen";
 import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteScreen";
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
@@ -256,6 +257,8 @@ function RootStackLayout(props: {
   useThreadOutboxDrain();
   // Presents the T3 Connect onboarding sheet after an in-session sign-in.
   useConnectOnboardingNavigation();
+  // Keeps the NewThread home-screen widget's project shortcuts current.
+  useNewThreadWidgetSync();
   // Full pathname (sheets included) for keyboard-command scoping; the
   // workspace layout only reacts to the underlying non-overlay route.
   const path = getPathFromState(props.state, navigationPathConfig);

apps/mobile/src/features/threads/new-thread-widget.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vite-plus/test";
+import type {
+  EnvironmentProject,
+  EnvironmentThreadShell,
+} from "@t3tools/client-runtime/state/shell";
+
+import {
+  makeNewThreadWidgetProps,
+  NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT,
+} from "./new-thread-widget";
+
+function makeProject(overrides: {
+  readonly id: string;
+  readonly environmentId?: string;
+  readonly title?: string;
+  readonly updatedAt?: string;
+}): EnvironmentProject {
+  return {
+    id: overrides.id,
+    environmentId: overrides.environmentId ?? "env-1",
+    title: overrides.title ?? overrides.id,
+    updatedAt: overrides.updatedAt ?? "2026-07-01T00:00:00.000Z",
+  } as unknown as EnvironmentProject;
+}
+
+function makeThread(overrides: {
+  readonly projectId: string;
+  readonly environmentId?: string;
+  readonly updatedAt: string;
+}): EnvironmentThreadShell {
+  return {
+    id: `thread-${overrides.projectId}`,
+    projectId: overrides.projectId,
+    environmentId: overrides.environmentId ?? "env-1",
+    updatedAt: overrides.updatedAt,
+  } as unknown as EnvironmentThreadShell;
+}
+
+describe("makeNewThreadWidgetProps", () => {
+  it("orders projects by their newest thread activity", () => {
+    const props = makeNewThreadWidgetProps(
+      [
+        makeProject({ id: "stale", updatedAt: "2026-07-06T00:00:00.000Z" }),
+        makeProject({ id: "busy", updatedAt: "2026-07-01T00:00:00.000Z" }),
+      ],
+      [makeThread({ projectId: "busy", updatedAt: "2026-07-07T00:00:00.000Z" })],
+    );
+    expect(props.projects?.map((project) => project.title)).toEqual(["busy", "stale"]);
+  });
+
+  it("falls back to the project's own updatedAt when it has no threads", () => {
+    const props = makeNewThreadWidgetProps(
+      [
+        makeProject({ id: "old", updatedAt: "2026-07-01T00:00:00.000Z" }),
+        makeProject({ id: "fresh", updatedAt: "2026-07-07T00:00:00.000Z" }),
+      ],
+      [],
+    );
+    expect(props.projects?.map((project) => project.title)).toEqual(["fresh", "old"]);
+  });
+
+  it("ignores thread activity from a same-named project in another environment", () => {
+    const props = makeNewThreadWidgetProps(
+      [
+        makeProject({ id: "proj", environmentId: "env-1", title: "one" }),
+        makeProject({
+          id: "proj",
+          environmentId: "env-2",
+          title: "two",
+          updatedAt: "2026-07-02T00:00:00.000Z",
+        }),
+      ],
+      [
+        makeThread({
+          projectId: "proj",
+          environmentId: "env-2",
+          updatedAt: "2026-07-07T00:00:00.000Z",
+        }),
+      ],
+    );
+    expect(props.projects?.map((project) => project.title)).toEqual(["two", "one"]);
+  });
+
+  it("caps the payload at the widget's sync limit", () => {
+    const props = makeNewThreadWidgetProps(
+      Array.from({ length: NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT + 5 }, (_, n) =>
+        makeProject({
+          id: `p${n}`,
+          updatedAt: `2026-06-${String(n + 1).padStart(2, "0")}T00:00:00.000Z`,
+        }),
+      ),
+      [],
+    );
+    expect(props.projects).toHaveLength(NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT);
+    expect(props.projects?.[0]?.title).toBe(`p${NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT + 4}`);
+  });
+
+  it("URL-encodes deep link parameters", () => {
+    const props = makeNewThreadWidgetProps(
+      [makeProject({ id: "p 1", environmentId: "env&1", title: "T3 & friends" })],
+      [],
+    );
+    expect(props.projects?.[0]?.deepLink).toBe(
+      "/new/draft?environmentId=env%261&projectId=p%201&title=T3%20%26%20friends",
+    );
+  });
+
+  it("returns an empty list when there are no projects", () => {
+    expect(makeNewThreadWidgetProps([], []).projects).toEqual([]);
+  });
+});

apps/mobile/src/features/threads/new-thread-widget.ts

@@ -0,0 +1,63 @@
+import type {
+  EnvironmentProject,
+  EnvironmentThreadShell,
+} from "@t3tools/client-runtime/state/shell";
+
+import type { NewThreadWidgetProps } from "../../widgets/NewThread";
+
+// Candidate pool synced to the widget. Deliberately larger than any family
+// displays (medium shows 3 rows, large 7): the "pinned projects" widget
+// configuration is per widget instance and only visible inside the widget
+// process, so the layout matches pins against this pool — a pin should still
+// resolve when its project is not among the most recent few.
+export const NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT = 20;
+
+/**
+ * Builds the home-screen widget payload: the most-recently-active projects,
+ * each with a deep link into the new-task draft composer for that project.
+ *
+ * "Recently active" means the newest thread update in the project, falling
+ * back to the project's own updatedAt for projects with no threads — so the
+ * widget surfaces where the user actually works, not what was created last.
+ */
+export function makeNewThreadWidgetProps(
+  projects: ReadonlyArray<EnvironmentProject>,
+  threads: ReadonlyArray<EnvironmentThreadShell>,
+): NewThreadWidgetProps {
+  const latestThreadActivity = new Map<string, string>();
+  for (const thread of threads) {
+    const key = projectActivityKey(thread.environmentId, thread.projectId);
+    const previous = latestThreadActivity.get(key);
+    // ISO-8601 timestamps order lexicographically.
+    if (previous === undefined || thread.updatedAt > previous) {
+      latestThreadActivity.set(key, thread.updatedAt);
+    }
+  }
+
+  const lastActivity = (project: EnvironmentProject): string => {
+    const threadActivity = latestThreadActivity.get(
+      projectActivityKey(project.environmentId, project.id),
+    );
+    return threadActivity !== undefined && threadActivity > project.updatedAt
+      ? threadActivity
+      : project.updatedAt;
+  };
+
+  const ordered = [...projects].sort((a, b) => lastActivity(b).localeCompare(lastActivity(a)));
+
+  return {
+    projects: ordered.slice(0, NEW_THREAD_WIDGET_PROJECT_SYNC_LIMIT).map((project) => ({
+      title: project.title,
+      // Matches the NewTaskSheet > NewTaskDraft linking config in Stack.tsx;
+      // the widget layout prefixes the scheme after a safety check.
+      deepLink:
+        `/new/draft?environmentId=${encodeURIComponent(String(project.environmentId))}` +
+        `&projectId=${encodeURIComponent(String(project.id))}` +
+        `&title=${encodeURIComponent(project.title)}`,
+    })),
+  };
+}
+
+function projectActivityKey(environmentId: string, projectId: string): string {
+  return `${environmentId}\u0000${projectId}`;
+}

apps/mobile/src/features/threads/use-new-thread-widget-sync.ts

@@ -0,0 +1,43 @@
+import { useEffect } from "react";
+import { Platform } from "react-native";
+
+import { useProjects, useThreadShells } from "../../state/entities";
+import NewThreadWidget from "../../widgets/NewThread";
+import { makeNewThreadWidgetProps } from "./new-thread-widget";
+
+// Last payload written to the widget timeline. Module-level (not React state)
+// so navigator remounts don't rewrite an unchanged payload: every write ends
+// in a WidgetCenter reload, and iOS throttles widgets that reload too often.
+let lastSyncedSignature: string | null = null;
+
+/**
+ * Keeps the NewThread home-screen widget's project shortcuts in sync with the
+ * workspace. Writing the snapshot also persists the widget layout to the
+ * shared app group, which is what lets the widget render at all — so this
+ * must run on every launch, not only when projects change.
+ */
+export function useNewThreadWidgetSync(): void {
+  const projects = useProjects();
+  const threads = useThreadShells();
+
+  useEffect(() => {
+    if (Platform.OS !== "ios") {
+      return;
+    }
+    const props = makeNewThreadWidgetProps(projects, threads);
+    const signature = JSON.stringify(props);
+    if (signature === lastSyncedSignature) {
+      return;
+    }
+    lastSyncedSignature = signature;
+    try {
+      NewThreadWidget.updateSnapshot(props);
+    } catch (error) {
+      // Clear the signature so the next data change retries the write.
+      lastSyncedSignature = null;
+      if (__DEV__) {
+        console.warn("[new-thread-widget] snapshot update failed", error);
+      }
+    }
+  }, [projects, threads]);
+}