@assembly-js/app-foundation 0.0.32 → 0.0.33

package/dist/next.js

@@ -1,25 +1,59 @@
+// Dev-invariant wrapper for generated apps' Next config. Each app's
+// next.config.ts is platform-owned boilerplate — `export default
+// withAssemblyDev(appConfig)` — so the preview invariants live here in the
+// versioned package instead of as config keys the build agent must know to
+// preserve when it edits its own app.config.ts.
+import * as fs from 'fs';
+import * as path from 'path';
+// Read non-root surface paths from the app manifest so location-prefix.ts can
+// discover them at runtime instead of relying on the hardcoded /c and /n defaults.
+function readSurfacePrefixes() {
+    try {
+        const manifestPath = path.join(process.cwd(), '.assembly', 'app.json');
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const prefixes = Object.values(manifest.surfaces ?? {})
+            .map((s) => s.path)
+            .filter((p) => typeof p === 'string' && p !== '/');
+        return prefixes.length > 0 ? JSON.stringify(prefixes) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function withAssemblyDev(config = {}) {
+    // Inject manifest-derived surface prefixes into the client bundle so
+    // location-prefix.ts honours whatever paths the app declares.
+    const surfacePrefixesJson = readSurfacePrefixes();
+    const baseConfig = surfacePrefixesJson
+        ? {
+            ...config,
+            env: {
+                ...config.env,
+                NEXT_PUBLIC_ASSEMBLY_SURFACE_PREFIXES: surfacePrefixesJson,
+            },
+        }
+        : config;
     // Production builds (deploys) have no dev server, no HMR socket, and no
-    // sandbox host — the wrapper is a pass-through there.
+    // sandbox host — only the env injection above applies there.
     if (process.env.NODE_ENV === 'production')
-        return config;
+        return baseConfig;
     const sandboxHost = process.env.SANDBOX_HOST;
     const allowedDevOrigins = sandboxHost
-        ? [...new Set([sandboxHost, ...(config.allowedDevOrigins ?? [])])]
-        : config.allowedDevOrigins;
+        ? [...new Set([sandboxHost, ...(baseConfig.allowedDevOrigins ?? [])])]
+        : baseConfig.allowedDevOrigins;
     // A dev WebSocket that never connects would otherwise hang hydration forever
     // on Next 16.3+. Debug data falls back to the flight stream, so
     // nothing user-visible is lost. Cast because this package type-checks against
     // its Next 15 devDependency, which predates the flag; runtimes that predate
     // it ignore the unknown key.
     const experimental = {
-        ...config.experimental,
+        ...baseConfig.experimental,
         reactDebugChannel: false,
     };
     return {
-        ...config,
+        ...baseConfig,
         ...(allowedDevOrigins ? { allowedDevOrigins } : {}),
-        devIndicators: config.devIndicators ?? false,
+        devIndicators: baseConfig.devIndicators ?? false,
         experimental,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-app-surfaces/SKILL.md

@@ -25,7 +25,7 @@ If you are unsure, default to **internal-only**. Do not add a client surface unl
 }
 ```
 
-- `internal` is **required** — every Vibe app must have a dashboard surface. `client` is optional; omit it for internal-only apps. `notification` is optional; declare it only when the app uses `ctaParams` in notifications (see below).
+- `internal` is **required** — every Vibe app must have a dashboard surface. `client` is optional; omit it for internal-only apps. `notification` is optional; declare it when opening a notification should land on a specific record (see below).
 - `path` is the route within your app for that surface. Must start with `/`. Use `/` for the surface's root; use distinct sub-paths if both surfaces share one Next.js app.
 - Generate the corresponding routes in your app code. E.g. if you declare `client.path = "/c"`, you must have a `/c` page in the app.
 
@@ -58,7 +58,7 @@ The app's API contract (automation triggers/actions, webhook events) is NOT an `
 
 ## The `notification` surface
 
-When an app sends notifications with `ctaParams`, the Notification Center needs to know where to send the user when they click the notification's CTA. Declare a `notification` surface to set that destination URL.
+When a notification should open a specific record, declare a `notification` surface. That path is what the Notification Center embeds; it is not a button the app renders.
 
 ```json
 {
@@ -71,10 +71,10 @@ When an app sends notifications with `ctaParams`, the Notification Center needs
 
 When `notification` is declared:
 - The build pipeline sets `notificationUrl` on the marketplace app to `<deployURL>/n`.
-- When a user clicks a notification CTA, the portal opens the app at `notificationUrl?token=<jwt>&<ctaParams>`.
+- Opening the notification embeds that URL in the Notification Center detail panel, with the token and `ctaParams` as search params. If `notificationUrl` is empty, the panel has no iframe: it shows the body and an "Open {app name}" button that opens the app's main view, and non-reserved `ctaParams` are forwarded as search params on that view.
 - Your `/n` page shows its context-specific content from the `ctaParams` in the URL. Those always arrive; `notificationId` from the token payload is best-effort under the session-exchange flow, so never gate the record render on it.
 
-**Declare the `notification` surface whenever the app sends notifications with `ctaParams`.** If notifications have no `ctaParams`, the surface is optional. See the `assembly-notifications` skill for the full CTA params pattern.
+**Declare the `notification` surface, and pass `ctaParams` that identify the record, whenever a notification should open that record.** A send with neither is only correct when the destination is the app's main view. See the `assembly-notifications` skill.
 
 ## Examples
 

package/skills/assembly-notifications/SKILL.md

@@ -29,7 +29,9 @@ The audience changes the experience and the code:
 
 ## Notification surfaces
 
-A surface is the embedded view the Notification Center renders when an internal user opens a notification. It's a route (conventionally `/n`) that reads the notification context — `notificationId` from the token payload plus your `ctaParams` — and renders the most useful thing: a filtered list of the items referenced, a single record with its key actions, or a status summary. When there's nothing more useful than "here's what happened, click to go deeper," skip it — the Notification Center then falls back to the title, body, and CTA from your `createNotification` call.
+A surface is the embedded view the Notification Center renders when an internal user opens a notification. It's a route (conventionally `/n`) that reads your `ctaParams` off the URL and renders the record they name.
+
+Declare the surface, and pass `ctaParams` that identify the record, whenever opening the notification should land on that record (one retainer, one submission, one task). Without the surface the Center shows the title and body, plus a platform button labeled "Open {app name}" that opens the app's main view. Non-reserved `ctaParams` are forwarded as search params on that main view. Skip the surface only when that main view is the right destination.
 
 Surfaces are internal-only. Clients don't render one, but `ctaParams` still travel with the notification and become URL search params on an email CTA click — that's how a client landing from an email gets enough context.
 
@@ -142,7 +144,7 @@ export async function GET() {
 - `senderType` — read-side only. Automatically populated from `senderId` (client, internal user, or company). You do not set it on create.
 - `deliveryTargets.inProduct` — include to make the notification appear in the Notification Center (for internal users) or trigger the badge (for clients). Requires `title`. `body` and `ctaParams` are optional. Omit entirely for email-only notifications.
 - `deliveryTargets.email` — include to send an email. `subject`, `header`, and `title` (CTA button label) are required, plus one body: `htmlBody` for formatted content (see below) or `body` for plain text. Either `inProduct` or `email` must be present; both is also valid.
-- `ctaParams` — a plain object of string key/value pairs that become URL search params when the user engages with the notification. Pass as an object — never `JSON.stringify()`. **Values must be strings** — stringify numbers and booleans yourself (e.g., `{ count: '3' }`, not `{ count: 3 }`). Nested objects aren't supported. Used by both the email CTA and the Notification Center surface.
+- `ctaParams` — a plain object of string key/value pairs that become URL search params when the user engages with the notification. Pass as an object — never `JSON.stringify()`. **Values must be strings** — stringify numbers and booleans yourself (e.g., `{ count: '3' }`, not `{ count: 3 }`). Nested objects aren't supported. Used by both the email CTA and the Notification Center surface. A notification about one record always includes the id that selects it (`{ retainerId: retainer.id }`). Title and body text do not.
 <!-- feature:notification-settings -->
 - `notificationSettingId` — the id of one of the app's declared notification settings (see "Per-user notification settings" below). Pass it on **every** send of a declared category so internal users' Product/Email toggles apply. Omit it for sends with no declared setting.
 <!-- /feature:notification-settings -->