@bridgeline-digital/hawk-app-cli 0.1.2-dev.20261027220454 → 0.1.2-dev.20261027234716

package/agents/AGENTS.md

@@ -161,6 +161,10 @@ host shows a PDF icon and downloads the whole page; mark buttons and filters `da
 (or `app.state.set` and `app.state.onApply`), so users can save, share and link views from HawkSearch's Views menu. One
 small JSON object, never the data.
 
+**Deep links:** an app that opens items (edit a widget, a rule) keeps where it is in the UI kit's `useRoute()`
+(`setRoute('/widgets/12')` on open, `setRoute('/')` on close) and shows the page from the route, so a reload or a link
+opens the same item and the browser's Back returns to the list. Stay on one Next.js page and switch on the route.
+
 **Ratings and reviews** need no code: users rate the app from HawkSearch's app header. To get each new review by email,
 declare `config.reviewEmails` (`{ "type": "emails" }`) and set it (`hawk-app config set reviewEmails …`).
 

package/docs/bridge/README.md

@@ -1471,6 +1471,26 @@ opened by a link reaches `onApply` even if the app registers it later. The UI ki
 (`const [filters, setFilters] = useSavedState({ range: 'l13', target: null })`). Errors: `invalid_request` (not a JSON
 object, too large). See the platform's docs/saved-views.md.
 
+## Deep links and Back
+
+An app that opens items (a widget, a rule, a report row) keeps where it is in the host's URL, so a reload or a shared
+link opens the same item, and the browser's Back returns to the list. Name the place with a route, a path from the
+app's start, and follow the route:
+
+```ts
+app.route.current;                                       // "/" at the start, or the route the page opened at
+app.route.set('/widgets/12');                            // the user opened widget 12: a new Back step
+app.route.set('/widgets/34', { replace: true });         // no Back step: a fix-up (a new item's id once saved)
+const stop = app.route.onChange((route) => show(route)); // Back, Forward, and the app's own set()
+```
+
+Show the page from the route (not from the click alone), so a link and Back land the same way. A route starts with
+`/`, has no `#`, and is at most 500 characters; query strings are fine (`/widgets/12?tab=layout`). The host keeps it in
+one query parameter of its own URL (HawkSearch: `?appRoute=`), next to its own. On a host without deep links,
+`set` still moves the app and tells the listeners, only the URL stays. The UI kit's `useRoute()` does both
+(`const [route, setRoute] = useRoute()`). Errors: `invalid_request` (not a route). A Next.js app's own routes are not
+the host's: keep the app on one page and switch on the route.
+
 ## Errors and usage
 
 `createApp` reports, on its own, one open per page load (the full app or the view showing), the screens and actions

package/docs/ui/README.md

@@ -52,6 +52,9 @@ export function Page() {
   page's state for the host's Views menu, and opening a saved view or its link sets it back.
   `const [filters, setFilters] = useSavedState({ range: 'l13', target: null })`. One small JSON object, once per page.
   See the bridge guide's "Saved views".
+- **`useRoute()`** is the app's route for deep links and Back: `const [route, setRoute] = useRoute()`, show the page
+  the route names, and `setRoute('/widgets/12')` when the user opens one (`{ replace: true }` for no Back step). The
+  host keeps it in its URL, so a reload or a link opens the same page. See the bridge guide's "Deep links and Back".
 - **`useScreen(name | null)`** counts a screen the routes don't show, such as a tab, each time it's shown:
   `useScreen('Logs')` in the tab's component. Routes and views are counted by the bridge, and so are clicks on
   `data-hawk-usage="Export CSV"` elements. See `hawk-app usage --screens` and the bridge guide's "Errors and usage".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.2-dev.20261027220454",
+  "version": "0.1.2-dev.20261027234716",
   "description": "For Bridgeline developers: create, deploy and register Hawk Apps (Services-built tools embedded in HawkSearch). Requires a Hawk Apps publisher key.",
   "author": "Bridgeline Digital",
   "license": "UNLICENSED",

package/src/dev.mjs

@@ -637,7 +637,7 @@ export function hostPage(settings) {
 <main>
   <div>
     <p id="title"></p>
-    <hawk-app-frame id="frame" title="${escapeHtml(settings.name)}"></hawk-app-frame>
+    <hawk-app-frame id="frame" title="${escapeHtml(settings.name)}" route-param="appRoute"></hawk-app-frame>
   </div>
   <aside>
     <section><h2>Token</h2><pre id="token">—</pre></section>
@@ -698,6 +698,7 @@ export function hostPage(settings) {
   frame.addEventListener('hawk-ready', () => event('ready'));
   frame.addEventListener('hawk-title', (e) => { $('title').textContent = e.detail.title; document.title = e.detail.title + ' · hawk-app dev'; event('setTitle: ' + e.detail.title); });
   frame.addEventListener('hawk-navigate', (e) => event('navigate: ' + JSON.stringify(e.detail)));
+  frame.addEventListener('hawk-route', (e) => event('route: ' + e.detail.route + (e.detail.replace ? ' (replace)' : '')));
   // "Explain this page" (the bar's button) reads this; HawkSearch shows the same button.
   frame.addEventListener('hawk-page-context', (e) => event('page context: ' + (e.detail.context ? JSON.stringify(e.detail.context).slice(0, 300) : 'cleared')));
   // The PDF icon (as in HawkSearch's bar) shows while the page allows it: app.setPdfExport / usePdfExport.