@synopackageland/sdk 0.49.5 → 0.50.1

package/README.md

@@ -17,7 +17,7 @@ App's `backend/go.mod`.
 
 `createDsmSession({read, write, fetch})` provides DSM session carriers for a
 desktop window or an Application Portal page. `ready()` returns the desktop's
-current token, or makes one shared, five-second, same-origin request to
+current token, or makes one shared, bounded, same-origin request to
 `webman/login.cgi?enable_syno_token=yes`. `token()` reads the current carrier.
 The optional `write` updates DSM's in-memory session for its own WebAPI client.
 Nothing is persisted. Recovery failure leaves the backend's existing
@@ -25,6 +25,23 @@ Nothing is persisted. Recovery failure leaves the backend's existing
 both the cookie and token. The CLI embeds this factory from the selected SDK
 into every generated native window, including Go-only Apps.
 
+An old page can retain a rejected token after another tab signs in again.
+`refresh(rejectedToken)` forces same-origin recovery while sharing concurrent
+requests. `createClient({sessionRetry: {session, operations}})` opts in to one
+retry for trusted `effect: read`, `kind: rpc` operations only. Writes, AI,
+streams and batches never replay; the default remains off because the client
+cannot infer operation effects. Existing `ctx.call` is not automatically wrapped.
+See [HTTPS and session recovery](../docs/https-and-session-recovery.md) for the
+API, cancellation/deadline behavior and the CLI skill link.
+
+Many Apps can use HTTP. Only Apps needing secure context, pairing or a strict
+HTTPS Origin policy should require it. Opt-in Go `api.RequireSecureOrigin`
+returns `https_required`; render `identityCopy(locale).httpsTitle` and
+`errors.https_required` with instructions to reopen through HTTPS.
+`readDsmHttpsURL(ctx, location.href)` discovers `dms_https` through
+`readDsmPorts` only for an administrator. Ordinary/unknown users get no
+PortInfo request and should see instructions only. No port is guessed.
+
 ## DSM WebAPI
 
 Every CLI-generated DSM window provides
@@ -48,7 +65,8 @@ native download form, which cannot set a header, puts it in its same-origin
 query.
 
 `readDsmPorts(ctx)` already prefers this channel and returns `[]` on refusal,
-unavailable data or its five-second deadline. It uses a same-origin token
+unavailable data or its request deadline. Call it only for an administrator;
+PortInfo can refuse ordinary sessions or close their DSM window. It uses a same-origin token
 request only without a window channel. `createNasProvider(ctx)` and executor
 scope selection also use `ctx.webApi` for File Station JSON calls, retaining
 App admission, validation, cancellation and deadlines. A channel refusal never
@@ -176,8 +194,7 @@ const ctx = createStandaloneContext({locale: 'zh-TW', call: (method, params) =>
 
 The default logo and app name return to the first entry in `pages` (including a
 hidden entry) through `v-model`. With no pages, activation changes no selection.
-This needs UI 0.14.3 or later; older supported
-UI versions keep their static brand. Pointer, Enter and Space share the same
+Use a matching UI release with brand activation support. Pointer, Enter and Space share the same
 native button action; the phone drawer closes on activation.
 
 `@brand` receives the original `MouseEvent`. To replace the default selection,
@@ -195,13 +212,39 @@ This does not change the DSM window title bar or DSM's own Portal header.
 a `title` the App has already translated, and optionally an `icon`, a `group`
 label (pages with the same label sit together), a `badge`, a `component` to
 render while it is the current page, `hidden` (reachable through `v-model`
-but not in the sidebar), its own `description`, `placement: 'bottom'` for a
-page the sidebar lists last, after every group (an App's settings), and
-`header: false` for a page that draws its own header. `fill: true` gives the page's body the height under
-its header and notices; the page does not scroll, so the content scrolls
-itself (a treemap, a table paged by height, a log viewer). The shell then
-holds to `100dvh`, so a phone's address bar does not leave a gap. The built-in `'status'` and `'background'`
-may sit in the same list.
+but not in the sidebar), `placement: 'bottom'` for a page the sidebar lists
+last, after every group (an App's settings), `header` and `fill`. The built-in
+`'status'` and `'background'` may sit in the same list.
+
+### Page title and actions
+
+The sidebar already names the page, so a page shows no title of its own and no
+subtitle. A visually hidden `h1` with the page's `title` still names it for
+screen readers. The `#actions` slot, `PageActions`, the `#meta` slot and
+`PageInfo` sit in a bar above the page: notes at the start, actions at the
+end. The bar stays in place while the page scrolls and shows only while it
+holds something. `header: true` shows the shell's `PageHeader` with the title
+and puts the notes and actions on its line instead. `header: false` is for a
+page that draws its own header: the shell adds no title, and its actions still
+go to the bar.
+
+### Scrolling
+
+The navigation, the page bar, a page's tabs and a settings footer stay in
+place; only the content scrolls, so no scrollbar runs past them. A page
+scrolls as a whole by default. A page that shows a `SettingsPage` or a
+`SectionTabs fill` fills the height instead: the tab strip stays at the top,
+the footer at the bottom edge of the window, and only the `SettingsPage` body
+scrolls (a tab that is not a `SettingsPage` scrolls under the strip). This
+works through the App's own wrappers, such as a template's
+`.integration-app > [data-page]`, with no CSS in the App. A page that shows a
+settings footer has no space under it, whether or not it sits in tabs.
+
+`fill: true` makes any page fill: the page does not scroll and the content
+scrolls itself (a treemap, a table paged by height, a log viewer). `fill: false`
+keeps a page scrolling as a whole even when it shows a `SettingsPage`. A filling
+shell holds to `100dvh`, so a phone's address bar does not leave a gap. On a
+phone the same rules give one scrolling area, with the footer in view.
 
 ```vue
 <AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="[
@@ -216,9 +259,10 @@ may sit in the same list.
 ```
 
 A page passed as `component` cannot fill the shell's `#actions` slot. It puts
-its own header buttons, such as its refresh, in `PageActions` anywhere in its
-template: they show in the page header before the App's `#actions` and leave
-with the page. Outside an `AppShell`, `PageActions` renders nothing.
+its own buttons, such as its refresh, in `PageActions` anywhere in its
+template: they show in the page bar (or the page header) before the App's
+`#actions` and leave with the page. Outside an `AppShell`, `PageActions`
+renders nothing.
 
 ```vue
 <!-- PackagesPage.vue -->
@@ -226,7 +270,8 @@ with the page. Outside an `AppShell`, `PageActions` renders nothing.
 ```
 
 A page's secondary notes take no row of their own: `PageInfo` puts them behind
-one info button on the title line, after the title and before the App's `#meta`.
+one info button at the start of the page bar (on the title line with
+`header: true`), before the App's `#meta`.
 The button is named "Notes (2)" in the shell's language (`label` names it
 otherwise); a click, or focus from the keyboard, opens the notes below it from
 its start, inside the App's window, and Escape closes them. The default slot
@@ -243,9 +288,8 @@ tested on its own provides `PageInfoTarget` as it does `PageActionsTarget`.
 horizontal bar in web and DSM window layouts. The `sidebar-footer` slot (or
 the account supplied by `ctx`) follows the navigation; mobile keeps its drawer.
 Omit `navigation` to keep the installed UI's default sidebar, or pass
-`navigation="sidebar"` explicitly. Top navigation requires
-**@synopackageland/ui 0.13.1 or later**; older supported UI peers keep their
-existing layout. Sidebar width and collapse preferences are unused in top mode.
+`navigation="sidebar"` explicitly. Use a matching `@synopackageland/ui` release
+with top navigation support. Sidebar width and collapse preferences are unused in top mode.
 
 ```vue
 <AppShell v-model="page" :locale="ctx.locale" :ctx="ctx" :pages="pages" navigation="top" />
@@ -263,22 +307,37 @@ surface at every width (web, DSM window and mobile):
 <AppShell v-model="page" :locale="ctx.locale" :ctx="ctx" :pages="pages" page-surface="none" />
 ```
 
-`none` requires **@synopackageland/ui 0.12.5 or later**. The SDK still accepts
-older UI peers and forwards the value unchanged, but those releases do not
-provide the no-surface/no-horizontal-gutter behavior. Other shell spacing,
+`none` requires a matching `@synopackageland/ui` release with no-surface support.
+Other shell spacing,
 including the body bottom padding, stays unchanged.
 
 Moving to another page starts it at the top; `keep-scroll` keeps the
-position. The `toolbar` slot sits above the page (in `AppLayout`'s toolbar)
-and `notices` in the page, under its header and inside the same padding, and
-scrolls with it. `activePage(current, pages)` keeps a selection that still exists and
+position. The `toolbar` slot sits above the page (in `AppLayout`'s toolbar,
+above the page bar) and `notices` at the top of the page, inside the same
+padding, and scrolls with it. `activePage(current, pages)` keeps a selection that still exists and
 otherwise picks the first page the sidebar shows. A router drives the shell
 through `v-model`:
 `:model-value="route.name" @update:model-value="name => router.push({name})"`.
 
+### Moving an existing App to these defaults
+
+- A page that should keep its visible title sets `header: true`. Pages carry no
+  subtitle: drop `description` from the page entries (it is no longer shown).
+- An App that set `header: false` only to hide the title, and added its own
+  hidden `h1`, can drop both: the shell now names the page itself. Buttons it
+  moved into its own `#toolbar` `AppToolbar` can go back to `#actions`.
+- Remove CSS that passed the height to a settings page, such as
+  `.integration-app > [data-page][data-fill] { flex: 1 1 0%; min-height: 0 }`
+  and the same rule for its child, and CSS that removed the space under a
+  settings footer (`.app-page-content:has(...) { padding-bottom: 0 }`).
+- Remove `fill: true` from pages whose content is a `SettingsPage` or a
+  `SectionTabs fill`; keep it for pages that scroll their own content, such as
+  a split view or a list paged by height. A page that must keep scrolling as a
+  whole while it shows a `SettingsPage` sets `fill: false`.
+
 Render the shell immediately, with [`EntryGuard`](../docs/app-entry.md) checking
 session/admin access in the background, and pass `loading` while startup reads
-run. The sidebar and title show immediately; the page body shows
+run. The sidebar and the page bar show immediately; the page body shows
 its loading area and the actions slot waits. With the current CLI/SDK, use
 `ctx.batch` for independent startup reads so they share one HTTP request and
 App process:
@@ -503,8 +562,8 @@ differ provides its adapter there, and the dialog reads as its settings
 page does.
 
 A full page, or a window DSM left open, keeps running the UI it loaded across
-a package upgrade until the page reloads (CLI 0.33.2+ windows opened after
-the upgrade load the new UI themselves). The CLI's DSM window (CLI 0.33.2+) gives `ctx.uiUpdate`: its `check()` reads the package's `ui/config`
+a package upgrade until the page reloads; windows opened after
+the upgrade load the new UI themselves. The CLI's DSM window gives `ctx.uiUpdate`: its `check()` reads the package's `ui/config`
 without the browser cache and answers whether the installed build replaced
 the window this page loaded. `AppShell` given that `ctx` shows
 `UiUpdateNotice` above every page once it answers yes: one line, Updated.