@assembly-js/app-foundation 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -19,6 +19,10 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.3.1
+- [guidance] The build agent now upgrades an app's bridge to 2.1.0 and its foundation package instead of skipping a deep link, mounts the location reporter, and deep-links notifications to the specific record.
+- [new] App destinations in `NavigateDestination` now accept an optional `path` for links to an app's inner page.
+
 ## 0.3.0
 - [new] `LocationReporter` is exported from `@assembly-js/app-foundation/client`, so apps born before the deeplink image can mount it in their layout and report their inner location to the host with the same surface-prefix handling as new apps.
 

package/CLAUDE.md

@@ -48,6 +48,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- feature:deep-link-bridge-nav -->
 - `assembly-platform-links` — link platform records (client, company, invoice, contract, form, file) to their portal detail page via `linkTo()`; never hand-build a host URL. Also links between workspace apps by install id. Check the app's installed app-bridge first (see the skill) — `navigateTo` doesn't exist on older peers — and only link staff-only destinations (client, company, form, etc.) from the dashboard surface, never the client portal.
 <!-- /feature:deep-link-bridge-nav -->
+<!-- feature:deep-link-app-inner-location -->
+- `assembly-app-inner-location` — mount `<LocationReporter />` so the host mirrors the app's inner page in its address bar; deep-link a notification or link to a specific record with `linkTo({ to: 'app', installId, path })`, never to the app root. Never hand-write location reporting.
+<!-- /feature:deep-link-app-inner-location -->
 <!-- feature:cross-app-apis -->
 - `assembly-app-clients` — calling another workspace app through its generated client in `generated/apps/<appId>/` (`installerClient`, by verb and path), and rendering an empty state that names the app when the call is refused instead of a 500.
 <!-- /feature:cross-app-apis -->

package/dist/bridge-vnext.d.ts

@@ -48,6 +48,7 @@ export type NavigateDestination = {
 } | {
     to: 'app';
     installId: string;
+    path?: string;
 };
 export type NavigateToOptions = {
     replace?: boolean;

package/package.json

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

package/skills/assembly-app-inner-location/SKILL.md

@@ -0,0 +1,19 @@
+<!-- feature:deep-link-app-inner-location -->
+---
+name: assembly-app-inner-location
+description: Use whenever the app has inner pages the host should mirror in its address bar, or when a notification, email or link should open this app on a specific record instead of its root. Covers mounting LocationReporter and pointing notifications at a specific record.
+---
+
+## What the reporter does
+
+The host mirrors the app's inner page in its own address bar and can open the app straight at an inner page. That only works if the app reports its location, and `<LocationReporter />` from the foundation package does exactly that. The reporter needs `AssemblyBridge.location`, which ships in app-bridge 2.1.0, and a `navigateTo`-only 2.0.0 bridge lacks it. Check with `grep -q onNavigate node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported`; if `unsupported`, run `bun add @assembly-js/app-bridge@2.1.0` (exact stable release, never a prerelease or range), then `bunx tsc --noEmit`, before mounting the reporter.
+
+- Mount `<LocationReporter />` once, in `app/layout.tsx`, imported from `@assembly-js/app-foundation/client`. If it is already there, leave it.
+- Never write custom `location.report` or `location.onNavigate` code, and never hand-write a `LocationSync` component. The reporter already handles surface prefixes and route changes.
+
+## Notifications deep-link to the record, not the app root
+
+When the app sends an email or in-product notification about a specific record (a document request, a submission), the destination is set by the notification's `ctaParams` and surface, not by `linkTo`. Pass `ctaParams` that identify the record (`ctaParams: { requestId: request.id }`) and render that record from an existing inner route of this app, one that works when opened cold. Follow `assembly-notifications` for the send-and-open pattern.
+
+To link from a button inside the app to an inner page, use `linkTo` as described in `assembly-platform-links` (the `app` destination takes an optional `path`).
+<!-- /feature:deep-link-app-inner-location -->

package/skills/assembly-platform-links/SKILL.md

@@ -14,7 +14,13 @@ Before writing any `linkTo()` or `AssemblyBridge.navigateTo()` call, check what
 grep -q navigateTo node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported
 ```
 
-If it reports `unsupported`, do not use this skill — there is no supported way for this app to trigger platform navigation yet. Skip the link rather than ship a button that silently does nothing.
+If it reports `unsupported`, upgrade the app in this same turn instead of skipping the link:
+
+1. Confirm the app is on the foundation package: `grep -q app-foundation package.json`. If it is not (vendored `lib/`), say the security update must land first and stop — do not attempt the migration in a feature turn.
+2. Pin the bridge to the exact stable release: `bun add @assembly-js/app-bridge@2.1.0`. Never pin a prerelease (`-beta`, `-rc`, `-next`) or a range.
+3. Bump the foundation dependency listed in `package.json` to `^0.3.0`, the floor that exports `linkTo` and `LocationReporter` (`bun add <that package name>@^0.3.0`).
+4. Run `bunx tsc --noEmit` and `bun run build`, and confirm the existing header and toast bridge calls still type-check. Fix any break before continuing.
+5. Re-run the check above, then proceed with this skill.
 
 ## When to reach for this skill
 
@@ -74,7 +80,7 @@ The host rejects staff-only destinations when the viewer is a client in the port
 | `article` | `articleId` | — | Yes |
 | `files` | — | `channelId` | Yes |
 | `channel` | — | `channelId` | Yes |
-| `app` | `installId` | — | Yes, if the target app is installed for that viewer |
+| `app` | `installId` | `path` | Yes, if the target app is installed for that viewer |
 | `home` | — | — | No — staff only |
 | `product` | — | — | No — staff only |
 | `helpdesk` | — | — | Yes |