@topogram/cli 0.3.57 → 0.3.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/generator/runtime/environment.js

@@ -370,16 +370,26 @@ function componentScriptOptions() {
   };
 }
 
+function runtimePortExpression(plan, runtimes, component, sharedEnvName) {
+  const runtimeEnvName = `${component.id.toUpperCase()}_PORT`;
+  const primaryRuntime = runtimes[0];
+  const fallback = primaryRuntime?.id === component.id
+    ? `\${${sharedEnvName}:-${component.port}}`
+    : `${component.port}`;
+  return `\${${runtimeEnvName}:-${fallback}}`;
+}
+
 function renderEnvironmentServerDevScript(plan, component = plan.runtimes.apis[0], options = {}) {
   if (!component) {
     return renderEnvAwareShellScript(['echo "No API runtimes are configured."']);
   }
   const guardPortsScript = options.componentScript ? '"$ROOT_DIR/scripts/guard-ports.mjs"' : '"$SCRIPT_DIR/guard-ports.mjs"';
+  const serverPortExpression = runtimePortExpression(plan, plan.runtimes.apis, component, "SERVER_PORT");
   return renderEnvAwareShellScript([
     `node ${guardPortsScript} api`,
     "",
     ...apiDatabaseExportLines(component),
-    `export PORT="\${${component.id.toUpperCase()}_PORT:-\${SERVER_PORT:-${component.port}}}"`,
+    `export PORT="${serverPortExpression}"`,
     `export TOPOGRAM_CORS_ORIGINS="\${TOPOGRAM_CORS_ORIGINS:-http://localhost:\${WEB_PORT:-${plan.ports.web}},http://127.0.0.1:\${WEB_PORT:-${plan.ports.web}}}"`,
     "",
     `cd "$ROOT_DIR/${component.dir}"`,
@@ -395,15 +405,16 @@ function renderEnvironmentWebDevScript(plan, component = plan.runtimes.webs[0],
   }
   const apiRuntime = plan.runtimes.apis.find((entry) => entry.id === component.uses_api) || plan.runtimes.apis[0];
   const guardPortsScript = options.componentScript ? '"$ROOT_DIR/scripts/guard-ports.mjs"' : '"$SCRIPT_DIR/guard-ports.mjs"';
+  const webPortExpression = runtimePortExpression(plan, plan.runtimes.webs, component, "WEB_PORT");
   return renderEnvAwareShellScript([
     `node ${guardPortsScript} web`,
     "",
     ...(apiRuntime ? [`export PUBLIC_TOPOGRAM_API_BASE_URL="\${PUBLIC_TOPOGRAM_API_BASE_URL:-http://localhost:\${${apiRuntime.id.toUpperCase()}_PORT:-\${SERVER_PORT:-${apiRuntime.port}}}}"`] : []),
-    `export TOPOGRAM_CORS_ORIGINS="\${TOPOGRAM_CORS_ORIGINS:-http://localhost:\${${component.id.toUpperCase()}_PORT:-\${WEB_PORT:-${component.port}}},http://127.0.0.1:\${${component.id.toUpperCase()}_PORT:-\${WEB_PORT:-${component.port}}}}"`,
+    `export TOPOGRAM_CORS_ORIGINS="\${TOPOGRAM_CORS_ORIGINS:-http://localhost:${webPortExpression},http://127.0.0.1:${webPortExpression}}"`,
     "",
     `cd "$ROOT_DIR/${component.dir}"`,
     "npm install",
-    `npm run dev -- --host "\${WEB_HOST:-127.0.0.1}" --port "\${${component.id.toUpperCase()}_PORT:-\${WEB_PORT:-${component.port}}}"`,
+    `npm run dev -- --host "\${WEB_HOST:-127.0.0.1}" --port "${webPortExpression}"`,
   ], options.componentScript ? componentScriptOptions() : {});
 }
 
@@ -450,8 +461,8 @@ ${startLines.length ? "wait" : ""}
 
 function renderEnvironmentGuardPortsScript(plan) {
   const ports = [
-    ...plan.runtimes.apis.map((component) => ({ id: component.id, type: "api", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "SERVER_PORT", port: component.port })),
-    ...plan.runtimes.webs.map((component) => ({ id: component.id, type: "web", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "WEB_PORT", port: component.port }))
+    ...plan.runtimes.apis.map((component, index) => ({ id: component.id, type: "api", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: index === 0 ? "SERVER_PORT" : null, port: component.port })),
+    ...plan.runtimes.webs.map((component, index) => ({ id: component.id, type: "web", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: index === 0 ? "WEB_PORT" : null, port: component.port }))
   ];
   return `#!/usr/bin/env node
 import net from "node:net";
@@ -461,7 +472,7 @@ const ports = ${JSON.stringify(ports, null, 2)};
 const expectedService = ${JSON.stringify(plan.runtimeReference.serviceName || "")};
 
 function effectivePort(entry) {
-  return Number(process.env[entry.env] || process.env[entry.fallbackEnv] || entry.port);
+  return Number(process.env[entry.env] || (entry.fallbackEnv ? process.env[entry.fallbackEnv] : "") || entry.port);
 }
 
 function portInUse(port) {

package/src/generator/surfaces/native/swiftui-app.js

@@ -26,13 +26,13 @@ export function generateSwiftUiApp(graph, options = {}) {
   const files = {};
 
   for (const name of swiftFiles) {
-    files[`Sources/TodoSwiftUIApp/${name}`] = fs.readFileSync(path.join(runtimeDir, name), "utf8");
+    files[`Sources/TopogramSwiftUIApp/${name}`] = fs.readFileSync(path.join(runtimeDir, name), "utf8");
   }
 
   files["Package.swift"] = fs.readFileSync(path.join(__dirname, "swiftui-templates", "Package.swift.txt"), "utf8");
   files["README.md"] = fs.readFileSync(path.join(__dirname, "swiftui-templates", "README.generated.md"), "utf8");
-  files["Sources/TodoSwiftUIApp/Resources/ui-surface-contract.json"] = contractJson;
-  files["Sources/TodoSwiftUIApp/Resources/api-contracts.json"] = apiJson;
+  files["Sources/TopogramSwiftUIApp/Resources/ui-surface-contract.json"] = contractJson;
+  files["Sources/TopogramSwiftUIApp/Resources/api-contracts.json"] = apiJson;
 
   return files;
 }

package/src/generator/surfaces/native/swiftui-templates/Package.swift.txt

@@ -2,15 +2,15 @@
 import PackageDescription
 
 let package = Package(
-    name: "TodoSwiftUIApp",
+    name: "TopogramSwiftUIApp",
     platforms: [.iOS(.v17), .macOS(.v14)],
     products: [
-        .executable(name: "TodoSwiftUIApp", targets: ["TodoSwiftUIApp"])
+        .executable(name: "TopogramSwiftUIApp", targets: ["TopogramSwiftUIApp"])
     ],
     targets: [
         .executableTarget(
-            name: "TodoSwiftUIApp",
-            path: "Sources/TodoSwiftUIApp",
+            name: "TopogramSwiftUIApp",
+            path: "Sources/TopogramSwiftUIApp",
             resources: [
                 .copy("Resources/api-contracts.json"),
                 .copy("Resources/ui-surface-contract.json")

package/src/generator/surfaces/native/swiftui-templates/README.generated.md

@@ -1,4 +1,4 @@
-# Todo SwiftUI (generated)
+# Topogram SwiftUI (generated)
 
 Apple SwiftUI client generated from the same **`buildWebRealization`** routed UI contract as the web stacks. Prefer the **`proj_ios_surface__swiftui`** projection when present; otherwise the generator falls back to a **`proj_web_surface__*`** projection (often **`proj_web_surface__sveltekit`**).
 
@@ -9,12 +9,12 @@ Apple SwiftUI client generated from the same **`buildWebRealization`** routed UI
 
 ## Run
 
-Open **`Package.swift`** in Xcode 15+ and run the **`TodoSwiftUIApp`** scheme on an iOS Simulator.
+Open **`Package.swift`** in Xcode 15+ and run the **`TopogramSwiftUIApp`** scheme on an iOS Simulator.
 
-Configure the API base URL and demo auth token via scheme environment variables (mirror web):
+Configure the API base URL and optional auth token via scheme environment variables (mirror web):
 
 - `PUBLIC_TOPOGRAM_API_BASE_URL` (default `http://localhost:3000`)
-- `PUBLIC_TOPOGRAM_DEMO_AUTH_TOKEN`
+- `PUBLIC_TOPOGRAM_AUTH_TOKEN`
 - Optional JWT / permission env vars matching web `visibility.ts` (`PUBLIC_TOPOGRAM_AUTH_*`).
 
 ## Regenerate

package/src/generator/surfaces/native/swiftui-templates/runtime/DynamicScreens.swift

@@ -1,12 +1,12 @@
 import SwiftUI
 
 /// Holds decoded ui-surface-contract.json for runtime-driven navigation (parity with web bundle).
-public final class TodoUiContract: ObservableObject {
+public final class TopogramUiContract: ObservableObject {
     public let raw: [String: Any]
 
     public init(data: Data) throws {
         guard let obj = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
-            throw NSError(domain: "TodoUiContract", code: 1)
+            throw NSError(domain: "TopogramUiContract", code: 1)
         }
         self.raw = obj
     }
@@ -14,7 +14,7 @@ public final class TodoUiContract: ObservableObject {
     public static func loadBundled() throws -> Data {
         guard let url = Bundle.module.url(forResource: "ui-surface-contract", withExtension: "json"),
               let data = try? Data(contentsOf: url) else {
-            throw NSError(domain: "TodoUiContract", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing ui-surface-contract.json"])
+            throw NSError(domain: "TopogramUiContract", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing ui-surface-contract.json"])
         }
         return data
     }
@@ -27,6 +27,12 @@ public final class TodoUiContract: ObservableObject {
         screens.first { ($0["id"] as? String) == id }
     }
 
+    public func firstScreen(kind: String, excluding excludedId: String? = nil) -> [String: Any]? {
+        screens.first {
+            ($0["kind"] as? String) == kind && ($0["id"] as? String) != excludedId
+        }
+    }
+
     public var tabItems: [NavigationItem] {
         guard let nav = raw["navigation"] as? [String: Any],
               let items = nav["items"] as? [[String: Any]] else {
@@ -63,10 +69,10 @@ public struct NavigationItem: Identifiable {
 }
 
 public struct RootTabView: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
 
-    public init(contract: TodoUiContract, client: TodoAPIClient) {
+    public init(contract: TopogramUiContract, client: TopogramAPIClient) {
         self.contract = contract
         self.client = client
     }
@@ -85,11 +91,11 @@ public struct RootTabView: View {
 }
 
 public struct DynamicScreenView: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let rootScreenId: String
 
-    public init(contract: TodoUiContract, client: TodoAPIClient, rootScreenId: String) {
+    public init(contract: TopogramUiContract, client: TopogramAPIClient, rootScreenId: String) {
         self.contract = contract
         self.client = client
         self.rootScreenId = rootScreenId
@@ -105,8 +111,8 @@ public struct DynamicScreenView: View {
 }
 
 struct ScreenSwitcher: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let screen: [String: Any]
     let baseParams: [String: String]
 
@@ -136,8 +142,8 @@ struct ScreenSwitcher: View {
 // MARK: - List
 
 struct ListScreen: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let screen: [String: Any]
     let baseParams: [String: String]
     @State private var rows: [[String: Any]] = []
@@ -148,10 +154,11 @@ struct ListScreen: View {
         let title = screen["title"] as? String ?? "List"
         let loadCap = (screen["loadCapability"] as? [String: Any])?["id"] as? String
         let screenId = screen["id"] as? String ?? ""
+        let filterFields = loadCap.map { client.queryFieldNames(for: $0) } ?? []
 
         VStack(alignment: .leading, spacing: 8) {
-            if screenId == "task_list" {
-                filterBar
+            if let loadCap, !filterFields.isEmpty {
+                filterBar(loadCap: loadCap, fields: filterFields)
             }
             if let errorText {
                 Text(errorText).foregroundStyle(.red)
@@ -161,7 +168,7 @@ struct ListScreen: View {
                 List(0 ..< rows.count, id: \.self) { i in
                     let row = rows[i]
                     NavigationLink {
-                        linkedDetail(row: row, listScreenId: screenId)
+                        linkedDetail(row: row)
                     } label: {
                         VStack(alignment: .leading) {
                             Text(rowTitle(row))
@@ -181,15 +188,10 @@ struct ListScreen: View {
                Visibility.canShowAction(pid, screen: screen, resource: nil) {
                 ToolbarItem(placement: .primaryAction) {
                     NavigationLink("Add") {
-                        linkedCreate(listScreenId: screenId)
+                        linkedCreate(currentScreenId: screenId)
                     }
                 }
             }
-            if screenId == "task_list", Visibility.canShowAction("cap_export_tasks", screen: screen, resource: nil) {
-                ToolbarItem(placement: .automatic) {
-                    ExportTasksButton(client: client, contract: contract)
-                }
-            }
         }
         .task {
             if let loadCap {
@@ -199,18 +201,18 @@ struct ListScreen: View {
     }
 
     @ViewBuilder
-    private var filterBar: some View {
+    private func filterBar(loadCap: String, fields: [String]) -> some View {
         VStack(alignment: .leading) {
             Text("Filters").font(.caption).foregroundStyle(.secondary)
             HStack {
-                TextField("project_id", text: bindingFilter("project_id"))
-                TextField("owner_id", text: bindingFilter("owner_id"))
-                TextField("status", text: bindingFilter("status"))
+                ForEach(fields, id: \.self) { field in
+                    TextField(field, text: bindingFilter(field))
+                }
             }
             .textFieldStyle(.roundedBorder)
             Button("Apply") {
                 Task {
-                    await reload(loadCap: "cap_list_tasks")
+                    await reload(loadCap: loadCap)
                 }
             }
         }
@@ -237,29 +239,19 @@ struct ListScreen: View {
     }
 
     @ViewBuilder
-    private func linkedDetail(row: [String: Any], listScreenId: String) -> some View {
-        let rid = row["id"] as? String ?? ""
-        if listScreenId.contains("task") {
-            DetailScreen(contract: contract, client: client, screen: contract.screen(id: "task_detail") ?? [:], params: ["task_id": rid])
-        } else if listScreenId.contains("project") {
-            DetailScreen(contract: contract, client: client, screen: contract.screen(id: "project_detail") ?? [:], params: ["project_id": rid])
-        } else if listScreenId.contains("user") {
-            DetailScreen(contract: contract, client: client, screen: contract.screen(id: "user_detail") ?? [:], params: ["user_id": rid])
+    private func linkedDetail(row: [String: Any]) -> some View {
+        if let detail = contract.firstScreen(kind: "detail") {
+            DetailScreen(contract: contract, client: client, screen: detail, params: navigationParams(for: detail, row: row, client: client))
         } else {
-            Text("Detail")
+            RowDetailFallback(row: row)
         }
     }
 
     @ViewBuilder
-    private func linkedCreate(listScreenId: String) -> some View {
-        switch listScreenId {
-        case "project_list":
-            FormScreen(client: client, contract: contract, screen: contract.screen(id: "project_create") ?? [:], params: [:])
-        case "user_list":
-            FormScreen(client: client, contract: contract, screen: contract.screen(id: "user_create") ?? [:], params: [:])
-        case "task_list", "task_board", "task_calendar":
-            FormScreen(client: client, contract: contract, screen: contract.screen(id: "task_create") ?? [:], params: [:])
-        default:
+    private func linkedCreate(currentScreenId: String) -> some View {
+        if let form = contract.firstScreen(kind: "form", excluding: currentScreenId) ?? contract.firstScreen(kind: "wizard", excluding: currentScreenId) {
+            FormScreen(client: client, contract: contract, screen: form, params: [:])
+        } else {
             Text("Create")
         }
     }
@@ -279,8 +271,8 @@ private func rowSubtitle(_ row: [String: Any]) -> String {
 // MARK: - Detail
 
 struct DetailScreen: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let screen: [String: Any]
     let params: [String: String]
     @State private var payload: [String: Any]?
@@ -310,7 +302,7 @@ struct DetailScreen: View {
         }
         .navigationTitle((screen["title"] as? String) ?? "Detail")
         .toolbar {
-            ToolbarItemGroup(placement: .bottomBar) {
+            ToolbarItemGroup(placement: .automatic) {
                 if let primary = (screen["actions"] as? [String: Any])?["primary"] as? [String: Any],
                    let cid = primary["id"] as? String {
                     NavigationLink("Edit") {
@@ -353,19 +345,12 @@ struct DetailScreen: View {
 
     @MainActor
     private func runSecondary(_ capabilityId: String) async {
-        guard capabilityId == "cap_complete_task",
-              let taskId = params["task_id"] ?? params["id"],
-              let detail = payload else { return }
-        let etag = String(describing: detail["updated_at"] ?? "")
         var headers: [String: String] = [:]
-        if !etag.isEmpty { headers["If-Match"] = etag }
-        let body: [String: Any] = [
-            "task_id": taskId,
-            "completed": true,
-            "idempotency_key": UUID().uuidString
-        ]
+        if let detail = payload, let updatedAt = detail["updated_at"] {
+            headers["If-Match"] = String(describing: updatedAt)
+        }
         do {
-            _ = try await client.requestCapability(capabilityId, input: body, extraHeaders: headers)
+            _ = try await client.requestCapability(capabilityId, input: params, extraHeaders: headers)
             await load()
         } catch {
             errorText = String(describing: error)
@@ -374,13 +359,8 @@ struct DetailScreen: View {
 
     @MainActor
     private func runDestructive(_ capabilityId: String) async {
-        guard let rid = params["task_id"] ?? params["project_id"] ?? params["user_id"] ?? params["id"] else { return }
-        var input: [String: Any] = [:]
-        if capabilityId.contains("task") { input["task_id"] = rid }
-        if capabilityId.contains("project") { input["project_id"] = rid }
-        if capabilityId.contains("user") { input["user_id"] = rid }
         do {
-            _ = try await client.requestCapability(capabilityId, input: input)
+            _ = try await client.requestCapability(capabilityId, input: params)
         } catch {
             errorText = String(describing: error)
         }
@@ -388,16 +368,22 @@ struct DetailScreen: View {
 
     @ViewBuilder
     private func editForm(cid: String) -> some View {
-        let sid = cid.contains("project") ? "project_edit" : cid.contains("user") ? "user_edit" : "task_edit"
-        FormScreen(client: client, contract: contract, screen: contract.screen(id: sid) ?? [:], params: params)
+        if let form = contract.screens.first(where: { screen in
+            guard let submit = (screen["submitCapability"] as? [String: Any])?["id"] as? String else { return false }
+            return submit == cid
+        }) ?? contract.firstScreen(kind: "form") {
+            FormScreen(client: client, contract: contract, screen: form, params: params)
+        } else {
+            Text("Edit")
+        }
     }
 }
 
 // MARK: - Form
 
 struct FormScreen: View {
-    let client: TodoAPIClient
-    @ObservedObject var contract: TodoUiContract
+    let client: TopogramAPIClient
+    @ObservedObject var contract: TopogramUiContract
     let screen: [String: Any]
     let params: [String: String]
     @State private var values: [String: String] = [:]
@@ -434,23 +420,16 @@ struct FormScreen: View {
     }
 
     private func preload() async {
-        guard let sid = screen["id"] as? String else { return }
-        if sid.contains("edit") {
-            let getCap = sid.contains("task") ? "cap_get_task" : sid.contains("project") ? "cap_get_project" : "cap_get_user"
-            var p = params
-            if sid.contains("task") { p["task_id"] = params["task_id"] ?? params["id"] ?? "" }
-            if sid.contains("project") { p["project_id"] = params["project_id"] ?? params["id"] ?? "" }
-            if sid.contains("user") { p["user_id"] = params["user_id"] ?? params["id"] ?? "" }
-            do {
-                let json = try await client.requestCapability(getCap, input: p)
-                if let dict = json as? [String: Any] {
-                    for key in dict.keys {
-                        values[key] = String(describing: dict[key] ?? "")
-                    }
+        guard let loadCap = (screen["loadCapability"] as? [String: Any])?["id"] as? String else { return }
+        do {
+            let json = try await client.requestCapability(loadCap, input: params)
+            if let dict = json as? [String: Any] {
+                for key in dict.keys {
+                    values[key] = String(describing: dict[key] ?? "")
                 }
-            } catch {
-                message = String(describing: error)
             }
+        } catch {
+            message = String(describing: error)
         }
     }
 
@@ -466,7 +445,7 @@ struct FormScreen: View {
             input[k] = v
         }
         var headers: [String: String] = [:]
-        if submitId == "cap_update_task", let etag = values["updated_at"] {
+        if let etag = values["updated_at"], !etag.isEmpty {
             headers["If-Match"] = etag
         }
         do {
@@ -478,59 +457,11 @@ struct FormScreen: View {
     }
 }
 
-extension TodoAPIClient {
-    func bodyFieldNames(for capabilityId: String) -> [String] {
-        guard let contract = contracts[capabilityId] as? [String: Any],
-              let rc = contract["requestContract"] as? [String: Any],
-              let transport = rc["transport"] as? [String: Any],
-              let body = transport["body"] as? [[String: Any]] else {
-            return []
-        }
-        return body.compactMap { $0["name"] as? String }
-    }
-}
-
-struct ExportTasksButton: View {
-    let client: TodoAPIClient
-    @ObservedObject var contract: TodoUiContract
-    @State private var jobId: String?
-
-    var body: some View {
-        Group {
-            if let jobId {
-                NavigationLink("Export job") {
-                    JobStatusScreen(
-                        client: client,
-                        contract: contract,
-                        screen: contract.screen(id: "task_exports") ?? [:],
-                        params: ["job_id": jobId]
-                    )
-                }
-            } else {
-                Button("Export") {
-                    Task { await run() }
-                }
-            }
-        }
-    }
-
-    private func run() async {
-        do {
-            let json = try await client.requestCapability("cap_export_tasks", input: [:])
-            if let dict = json as? [String: Any], let id = dict["job_id"] as? String {
-                jobId = id
-            }
-        } catch {
-            jobId = nil
-        }
-    }
-}
-
 // MARK: - Board & Calendar
 
 struct BoardScreen: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let screen: [String: Any]
     let baseParams: [String: String]
     @State private var rows: [[String: Any]] = []
@@ -549,8 +480,8 @@ struct BoardScreen: View {
                             DetailScreen(
                                 contract: contract,
                                 client: client,
-                                screen: contract.screen(id: "task_detail") ?? [:],
-                                params: ["task_id": row["id"] as? String ?? ""]
+                                screen: contract.firstScreen(kind: "detail") ?? [:],
+                                params: navigationParams(for: contract.firstScreen(kind: "detail") ?? [:], row: row, client: client)
                             )
                         } label: {
                             Text(rowTitle(row))
@@ -578,8 +509,8 @@ struct BoardScreen: View {
 }
 
 struct CalendarScreen: View {
-    @ObservedObject var contract: TodoUiContract
-    let client: TodoAPIClient
+    @ObservedObject var contract: TopogramUiContract
+    let client: TopogramAPIClient
     let screen: [String: Any]
     let baseParams: [String: String]
     @State private var rows: [[String: Any]] = []
@@ -602,8 +533,8 @@ struct CalendarScreen: View {
                             DetailScreen(
                                 contract: contract,
                                 client: client,
-                                screen: contract.screen(id: "task_detail") ?? [:],
-                                params: ["task_id": row["id"] as? String ?? ""]
+                                screen: contract.firstScreen(kind: "detail") ?? [:],
+                                params: navigationParams(for: contract.firstScreen(kind: "detail") ?? [:], row: row, client: client)
                             )
                         } label: {
                             Text(rowTitle(row))
@@ -630,8 +561,8 @@ struct CalendarScreen: View {
 }
 
 struct JobStatusScreen: View {
-    let client: TodoAPIClient
-    @ObservedObject var contract: TodoUiContract
+    let client: TopogramAPIClient
+    @ObservedObject var contract: TopogramUiContract
     let screen: [String: Any]
     let params: [String: String]
     @State private var job: [String: Any]?
@@ -672,11 +603,45 @@ struct JobStatusScreen: View {
     }
 
     private func download(_ capabilityId: String) async {
-        let jobId = params["job_id"] ?? ""
         do {
-            _ = try await client.requestCapability(capabilityId, input: ["job_id": jobId])
+            _ = try await client.requestCapability(capabilityId, input: params)
         } catch {
             // ignore download errors in stub
         }
     }
 }
+
+struct RowDetailFallback: View {
+    let row: [String: Any]
+
+    var body: some View {
+        List(Array(row.keys.sorted()), id: \.self) { key in
+            HStack {
+                Text(key).foregroundStyle(.secondary)
+                Spacer()
+                Text(String(describing: row[key] ?? ""))
+            }
+        }
+        .navigationTitle(rowTitle(row))
+    }
+}
+
+private func navigationParams(for screen: [String: Any], row: [String: Any], client: TopogramAPIClient) -> [String: String] {
+    guard let cap = (screen["loadCapability"] as? [String: Any])?["id"] as? String else {
+        return row.compactMapValues { $0 as? String }
+    }
+    let pathFields = client.pathFieldNames(for: cap)
+    if pathFields.isEmpty {
+        return row.compactMapValues { $0 as? String }
+    }
+    var params: [String: String] = [:]
+    let fallbackId = row["id"].map { String(describing: $0) } ?? ""
+    for field in pathFields {
+        if let value = row[field] {
+            params[field] = String(describing: value)
+        } else if !fallbackId.isEmpty {
+            params[field] = fallbackId
+        }
+    }
+    return params
+}

package/src/generator/surfaces/native/swiftui-templates/runtime/{TodoAPIClient.swift → TopogramAPIClient.swift}

@@ -1,13 +1,13 @@
 import Foundation
 
 /// Dynamic capability client mirroring `src/lib/api/client.ts` (requestCapability over bundled api-contracts.json).
-public final class TodoAPIClient: @unchecked Sendable {
+public final class TopogramAPIClient: @unchecked Sendable {
     private let session: URLSession
     let contracts: [String: Any]
     public init(session: URLSession = .shared, contractsData: Data) throws {
         self.session = session
         guard let root = try JSONSerialization.jsonObject(with: contractsData) as? [String: Any] else {
-            throw TodoAPIError.invalidContracts
+            throw TopogramAPIError.invalidContracts
         }
         self.contracts = root
     }
@@ -15,7 +15,7 @@ public final class TodoAPIClient: @unchecked Sendable {
     public static func loadBundledContracts() throws -> Data {
         guard let url = Bundle.module.url(forResource: "api-contracts", withExtension: "json"),
               let data = try? Data(contentsOf: url) else {
-            throw TodoAPIError.missingResource("api-contracts.json")
+            throw TopogramAPIError.missingResource("api-contracts.json")
         }
         return data
     }
@@ -26,13 +26,34 @@ public final class TodoAPIClient: @unchecked Sendable {
     }
 
     private func authToken() -> String {
-        ProcessInfo.processInfo.environment["PUBLIC_TOPOGRAM_DEMO_AUTH_TOKEN"] ?? ""
+        ProcessInfo.processInfo.environment["PUBLIC_TOPOGRAM_AUTH_TOKEN"] ?? ""
+    }
+
+    private func transportFields(for capabilityId: String, section: String) -> [[String: Any]] {
+        guard let contract = contracts[capabilityId] as? [String: Any],
+              let requestContract = contract["requestContract"] as? [String: Any],
+              let transport = requestContract["transport"] as? [String: Any] else {
+            return []
+        }
+        return transport[section] as? [[String: Any]] ?? []
+    }
+
+    public func pathFieldNames(for capabilityId: String) -> [String] {
+        transportFields(for: capabilityId, section: "path").compactMap { $0["name"] as? String }
+    }
+
+    public func queryFieldNames(for capabilityId: String) -> [String] {
+        transportFields(for: capabilityId, section: "query").compactMap { $0["name"] as? String }
+    }
+
+    public func bodyFieldNames(for capabilityId: String) -> [String] {
+        transportFields(for: capabilityId, section: "body").compactMap { $0["name"] as? String }
     }
 
     private func buildPath(contract: [String: Any], input: [String: Any]) throws -> String {
         guard let endpoint = contract["endpoint"] as? [String: Any],
               let rawPath = endpoint["path"] as? String else {
-            throw TodoAPIError.invalidContracts
+            throw TopogramAPIError.invalidContracts
         }
         var path = rawPath
         let requestContract = contract["requestContract"] as? [String: Any]
@@ -78,15 +99,15 @@ public final class TodoAPIClient: @unchecked Sendable {
         extraHeaders: [String: String] = [:]
     ) async throws -> Any {
         guard let contract = contracts[capabilityId] as? [String: Any] else {
-            throw TodoAPIError.unknownCapability(capabilityId)
+            throw TopogramAPIError.unknownCapability(capabilityId)
         }
         guard let endpoint = contract["endpoint"] as? [String: Any],
               let method = endpoint["method"] as? String else {
-            throw TodoAPIError.invalidContracts
+            throw TopogramAPIError.invalidContracts
         }
         let path = try buildPath(contract: contract, input: input)
         guard let url = URL(string: path, relativeTo: URL(string: apiBase()))?.absoluteURL else {
-            throw TodoAPIError.badURL(path)
+            throw TopogramAPIError.badURL(path)
         }
         var request = URLRequest(url: url)
         request.httpMethod = method
@@ -121,11 +142,11 @@ public final class TodoAPIClient: @unchecked Sendable {
         let downloadable = endpoint["download"] as? [[String: Any]] ?? []
         let (data, response) = try await session.data(for: request)
         guard let http = response as? HTTPURLResponse else {
-            throw TodoAPIError.invalidResponse
+            throw TopogramAPIError.invalidResponse
         }
         guard (200 ..< 300).contains(http.statusCode) else {
             let text = String(data: data, encoding: .utf8) ?? ""
-            throw TodoAPIError.http(http.statusCode, text)
+            throw TopogramAPIError.http(http.statusCode, text)
         }
         if http.statusCode == 204 {
             return NSNull()
@@ -146,7 +167,7 @@ public final class TodoAPIClient: @unchecked Sendable {
     }
 }
 
-public enum TodoAPIError: Error {
+public enum TopogramAPIError: Error {
     case invalidContracts
     case missingResource(String)
     case unknownCapability(String)

package/src/generator/surfaces/native/swiftui-templates/runtime/{TodoSwiftUIApp.swift → TopogramSwiftUIApp.swift}

@@ -1,7 +1,7 @@
 import SwiftUI
 
 @main
-struct TodoSwiftUIApp: App {
+struct TopogramSwiftUIApp: App {
     @StateObject private var contractHolder = ContractHolder()
 
     var body: some Scene {
@@ -13,7 +13,7 @@ struct TodoSwiftUIApp: App {
                     Text("Failed to load Topogram UI contract: \(err)")
                         .padding()
                 } else {
-                    ProgressView("Loading Topogram Todo…")
+                    ProgressView("Loading Topogram UI…")
                 }
             }
             .task {
@@ -25,16 +25,16 @@ struct TodoSwiftUIApp: App {
 
 @MainActor
 final class ContractHolder: ObservableObject {
-    @Published var contract: TodoUiContract?
-    @Published var client: TodoAPIClient?
+    @Published var contract: TopogramUiContract?
+    @Published var client: TopogramAPIClient?
     @Published var error: String?
 
     func bootstrap() async {
         do {
-            let uiData = try TodoUiContract.loadBundled()
-            let apiData = try TodoAPIClient.loadBundledContracts()
-            let ui = try TodoUiContract(data: uiData)
-            let cli = try TodoAPIClient(contractsData: apiData)
+            let uiData = try TopogramUiContract.loadBundled()
+            let apiData = try TopogramAPIClient.loadBundledContracts()
+            let ui = try TopogramUiContract(data: uiData)
+            let cli = try TopogramAPIClient(contractsData: apiData)
             contract = ui
             client = cli
         } catch {

package/src/generator/surfaces/native/swiftui-templates/runtime/Visibility.swift

@@ -108,11 +108,12 @@ public enum Visibility {
     }
 
     private static func currentPrincipal(overrides: PrincipalOverride?) -> Principal? {
-        let token = env("PUBLIC_TOPOGRAM_DEMO_AUTH_TOKEN")
+        let token = env("PUBLIC_TOPOGRAM_AUTH_TOKEN")
         let jwtPrincipal = token.isEmpty ? nil : principalFromJwt(token)
         let envClaims = parseClaims(env("PUBLIC_TOPOGRAM_AUTH_CLAIMS"))
+        let envUserId = env("PUBLIC_TOPOGRAM_AUTH_USER_ID")
         let userId = overrides?.userId
-            ?? env("PUBLIC_TOPOGRAM_AUTH_USER_ID")
+            ?? (!envUserId.isEmpty ? envUserId : nil)
             ?? jwtPrincipal?.userId
             ?? ""
 

package/src/project-config.js

@@ -305,128 +305,128 @@ function validateOutputConfig(errors, config) {
 }
 
 /**
- * @param {any} component
+ * @param {any} runtime
  * @returns {string}
  */
-function componentLabel(component) {
-  return component?.id ? `Runtime '${component.id}'` : "Topology runtime";
+function runtimeLabel(runtime) {
+  return runtime?.id ? `Runtime '${runtime.id}'` : "Topology runtime";
 }
 
 /**
  * @param {ValidationError[]} errors
- * @param {any} component
+ * @param {any} runtime
  * @param {Set<string>} seenIds
  * @returns {boolean}
  */
-function validateComponentShape(errors, component, seenIds) {
-  if (!component || typeof component !== "object" || Array.isArray(component)) {
+function validateRuntimeShape(errors, runtime, seenIds) {
+  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) {
     pushError(errors, "Topology runtime must be an object");
     return false;
   }
-  if (typeof component.id !== "string" || !IDENTIFIER_PATTERN.test(component.id)) {
-    pushError(errors, `${componentLabel(component)} id must match ${IDENTIFIER_PATTERN}`);
-  } else if (seenIds.has(component.id)) {
-    pushError(errors, `Duplicate topology runtime id '${component.id}'`);
+  if (typeof runtime.id !== "string" || !IDENTIFIER_PATTERN.test(runtime.id)) {
+    pushError(errors, `${runtimeLabel(runtime)} id must match ${IDENTIFIER_PATTERN}`);
+  } else if (seenIds.has(runtime.id)) {
+    pushError(errors, `Duplicate topology runtime id '${runtime.id}'`);
   } else {
-    seenIds.add(component.id);
+    seenIds.add(runtime.id);
   }
-  if (component.type != null) {
-    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'type'", "'kind'", `"kind": "api_service"`)}`);
+  if (runtime.type != null) {
+    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'type'", "'kind'", `"kind": "api_service"`)}`);
   }
-  if (component.database != null) {
-    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'database'", "'uses_database'", `"uses_database": "app_db"`)}`);
+  if (runtime.database != null) {
+    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'database'", "'uses_database'", `"uses_database": "app_db"`)}`);
   }
-  if (component.api != null) {
-    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'api'", "'uses_api'", `"uses_api": "app_api"`)}`);
+  if (runtime.api != null) {
+    pushError(errors, `${runtimeLabel(runtime)} ${renameDiagnostic("'api'", "'uses_api'", `"uses_api": "app_api"`)}`);
   }
-  if (!["api_service", "web_surface", "ios_surface", "android_surface", "database"].includes(component.kind)) {
-    pushError(errors, `${componentLabel(component)} kind must be api_service, web_surface, ios_surface, android_surface, or database`);
+  if (!["api_service", "web_surface", "ios_surface", "android_surface", "database"].includes(runtime.kind)) {
+    pushError(errors, `${runtimeLabel(runtime)} kind must be api_service, web_surface, ios_surface, android_surface, or database`);
   }
-  if (typeof component.projection !== "string" || component.projection.length === 0) {
-    pushError(errors, `${componentLabel(component)} projection must be a non-empty string`);
+  if (typeof runtime.projection !== "string" || runtime.projection.length === 0) {
+    pushError(errors, `${runtimeLabel(runtime)} projection must be a non-empty string`);
   }
-  if (!component.generator || typeof component.generator !== "object") {
-    pushError(errors, `${componentLabel(component)} generator must be an object`);
+  if (!runtime.generator || typeof runtime.generator !== "object") {
+    pushError(errors, `${runtimeLabel(runtime)} generator must be an object`);
   } else {
-    if (typeof component.generator.id !== "string" || component.generator.id.length === 0) {
-      pushError(errors, `${componentLabel(component)} generator.id must be a non-empty string`);
+    if (typeof runtime.generator.id !== "string" || runtime.generator.id.length === 0) {
+      pushError(errors, `${runtimeLabel(runtime)} generator.id must be a non-empty string`);
     }
-    if (typeof component.generator.version !== "string" || component.generator.version.length === 0) {
-      pushError(errors, `${componentLabel(component)} generator.version must be a non-empty string`);
+    if (typeof runtime.generator.version !== "string" || runtime.generator.version.length === 0) {
+      pushError(errors, `${runtimeLabel(runtime)} generator.version must be a non-empty string`);
     }
-    if (component.generator.package != null && (typeof component.generator.package !== "string" || component.generator.package.length === 0)) {
-      pushError(errors, `${componentLabel(component)} generator.package must be a non-empty string when provided`);
+    if (runtime.generator.package != null && (typeof runtime.generator.package !== "string" || runtime.generator.package.length === 0)) {
+      pushError(errors, `${runtimeLabel(runtime)} generator.package must be a non-empty string when provided`);
     }
   }
-  if (component.port != null && (!Number.isInteger(component.port) || component.port <= 0 || component.port > 65535)) {
-    pushError(errors, `${componentLabel(component)} port must be an integer from 1 to 65535`);
+  if (runtime.port != null && (!Number.isInteger(runtime.port) || runtime.port <= 0 || runtime.port > 65535)) {
+    pushError(errors, `${runtimeLabel(runtime)} port must be an integer from 1 to 65535`);
   }
   return true;
 }
 
 /**
  * @param {ValidationError[]} errors
- * @param {RuntimeTopologyRuntime} component
+ * @param {RuntimeTopologyRuntime} runtime
  * @param {Map<string, Record<string, any>>} projections
  * @param {{ configDir?: string|null, rootDir?: string|null }} [options]
  * @returns {void}
  */
-function validateComponentCompatibility(errors, component, projections, options = {}) {
-  const projection = projections.get(component.projection);
+function validateRuntimeCompatibility(errors, runtime, projections, options = {}) {
+  const projection = projections.get(runtime.projection);
   if (!projection) {
-    pushError(errors, `${componentLabel(component)} references missing projection '${component.projection}'`);
+    pushError(errors, `${runtimeLabel(runtime)} references missing projection '${runtime.projection}'`);
     return;
   }
 
-  const resolvedManifest = resolveGeneratorManifestForBinding(component.generator, options);
+  const resolvedManifest = resolveGeneratorManifestForBinding(runtime.generator, options);
   const manifest = resolvedManifest.manifest;
   if (!manifest) {
     const details = resolvedManifest.errors.length > 0 ? `: ${resolvedManifest.errors.join("; ")}` : "";
-    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' uses unknown generator '${component.generator?.id}' version '${component.generator?.version || "unknown"}'${details}`);
+    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' uses unknown generator '${runtime.generator?.id}' version '${runtime.generator?.version || "unknown"}'${details}`);
     return;
   }
   const manifestValidation = validateGeneratorManifest(manifest);
   if (!manifestValidation.ok) {
     for (const message of manifestValidation.errors) {
-      pushError(errors, `${componentLabel(component)} generator manifest invalid: ${message}`);
+      pushError(errors, `${runtimeLabel(runtime)} generator manifest invalid: ${message}`);
     }
   }
   if (manifest.planned) {
-    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' uses planned generator '${manifest.id}@${manifest.version}', which is not implemented yet`);
+    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' uses planned generator '${manifest.id}@${manifest.version}', which is not implemented yet`);
   }
-  if (manifest.version !== component.generator.version) {
-    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' generator '${manifest.id}' version '${component.generator.version}' is unsupported; expected '${manifest.version}'`);
+  if (manifest.version !== runtime.generator.version) {
+    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' generator '${manifest.id}' version '${runtime.generator.version}' is unsupported; expected '${manifest.version}'`);
   }
-  if (!isGeneratorCompatible(manifest, component.kind, projection)) {
-    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' generator '${manifest.id}@${manifest.version}' is incompatible with runtime kind '${component.kind}' and projection type '${projection.type || "api_contract"}'`);
+  if (!isGeneratorCompatible(manifest, runtime.kind, projection)) {
+    pushError(errors, `${runtimeLabel(runtime)} for projection '${projection.id}' generator '${manifest.id}@${manifest.version}' is incompatible with runtime kind '${runtime.kind}' and projection type '${projection.type || "api_contract"}'`);
   }
 }
 
 /**
  * @param {ValidationError[]} errors
- * @param {RuntimeTopologyRuntime[]} components
+ * @param {RuntimeTopologyRuntime[]} runtimes
  * @returns {void}
  */
-function validateTopologyReferences(errors, components) {
-  const byId = new Map(components.map((component) => [component.id, component]));
+function validateTopologyReferences(errors, runtimes) {
+  const byId = new Map(runtimes.map((runtime) => [runtime.id, runtime]));
   const usedPorts = new Map();
-  for (const component of components) {
-    if (component.port != null) {
-      const existing = usedPorts.get(component.port);
+  for (const runtime of runtimes) {
+    if (runtime.port != null) {
+      const existing = usedPorts.get(runtime.port);
       if (existing) {
-        pushError(errors, `Port ${component.port} is used by both '${existing}' and '${component.id}'`);
+        pushError(errors, `Port ${runtime.port} is used by both '${existing}' and '${runtime.id}'`);
       } else {
-        usedPorts.set(component.port, component.id);
+        usedPorts.set(runtime.port, runtime.id);
       }
     }
-    if (component.kind === "api_service") {
-      if (component.uses_database && byId.get(component.uses_database)?.kind !== "database") {
-        pushError(errors, `${componentLabel(component)} references missing database runtime '${component.uses_database}'`);
+    if (runtime.kind === "api_service") {
+      if (runtime.uses_database && byId.get(runtime.uses_database)?.kind !== "database") {
+        pushError(errors, `${runtimeLabel(runtime)} references missing database runtime '${runtime.uses_database}'`);
       }
     }
-    if (["web_surface", "ios_surface", "android_surface"].includes(component.kind)) {
-      if (component.uses_api && byId.get(component.uses_api)?.kind !== "api_service") {
-        pushError(errors, `${componentLabel(component)} references missing api runtime '${component.uses_api}'`);
+    if (["web_surface", "ios_surface", "android_surface"].includes(runtime.kind)) {
+      if (runtime.uses_api && byId.get(runtime.uses_api)?.kind !== "api_service") {
+        pushError(errors, `${runtimeLabel(runtime)} references missing api runtime '${runtime.uses_api}'`);
       }
     }
   }
@@ -455,8 +455,8 @@ export function validateProjectConfig(config, graph = null, options = {}) {
     pushError(errors, "topogram.project.json topology.runtimes must be an array");
   } else {
     const seenIds = new Set();
-    for (const component of config.topology.runtimes) {
-      validateComponentShape(errors, component, seenIds);
+    for (const runtime of config.topology.runtimes) {
+      validateRuntimeShape(errors, runtime, seenIds);
     }
     const generatorPolicy = validateProjectGeneratorPolicy(config, options);
     for (const error of generatorPolicy.errors) {
@@ -464,8 +464,8 @@ export function validateProjectConfig(config, graph = null, options = {}) {
     }
     if (graph) {
       const projections = projectionById(graph);
-      for (const component of config.topology.runtimes) {
-        validateComponentCompatibility(errors, component, projections, options);
+      for (const runtime of config.topology.runtimes) {
+        validateRuntimeCompatibility(errors, runtime, projections, options);
       }
       validateTopologyReferences(errors, config.topology.runtimes);
     }