Merge remote-tracking branch 'origin/main' into feat/dock-group-shortcuts

# Conflicts:
#	docs/content/8.references/6.hub-api.md

Author: antfubot

.github/workflows/ci.yml

@@ -18,6 +18,38 @@ jobs:
       lint: pnpm run lint && pnpm run knip
       build-for-lint: true
 
+  # The RPC transport binds a native WebSocket on Bun/Deno (crossws's
+  # Bun/Deno adapters over `Bun.serve` / `Deno.serve`) and falls back to SSE
+  # for a shared foreign `node:http` server. This runs the cross-runtime smoke
+  # test under each runtime so that binding can't regress (issue #317).
+  runtime:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [bun, deno]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Set up Bun
+        if: matrix.runtime == 'bun'
+        uses: oven-sh/setup-bun@v2
+      - name: Set up Deno
+        if: matrix.runtime == 'deno'
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      - run: pnpm install --frozen-lockfile
+      - name: Build devframe
+        run: pnpm --filter devframe run build
+      - name: Run the ${{ matrix.runtime }} RPC transport smoke test
+        run: pnpm run test:runtime:${{ matrix.runtime }}
+
   e2e:
     runs-on: ubuntu-latest
     timeout-minutes: 15

alias.ts

@@ -34,6 +34,7 @@ export const alias = {
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/nostics': r('devframe/src/utils/nostics.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
+  'devframe/utils/origin': r('devframe/src/utils/origin.ts'),
   'devframe/utils/remote-assets': r('devframe/src/utils/remote-assets.ts'),
   'devframe/utils/simple-schema': r('devframe/src/utils/simple-schema.ts'),
   'devframe/utils/serve-static': r('devframe/src/utils/serve-static.ts'),

docs/app/app.config.ts

@@ -9,8 +9,7 @@ export default defineAppConfig({
     title: 'Devframe',
     logo: {
       alt: 'Devframe',
-      light: '/logo.svg',
-      dark: '/logo.svg',
+      mark: 'devframe',
     },
     nav: [
       {

docs/app/components/LogoMark.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+defineProps<{
+  name?: string
+}>()
+</script>
+
+<template>
+  <svg class="h-6 w-auto" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <g filter="url(#filter0_d_8_208)">
+      <path d="M238.464 40H66V236.007H104.577C220.688 236.007 232.79 158.437 232.79 121.733C232.79 108.867 243.38 108.867 243.38 121.733C251.318 236.701 356.35 245.457 365.527 246.223L365.542 246.224C374.619 246.981 382.561 251.521 365.542 254.548C253.592 264.765 243.758 364.282 243.38 375.634C243.002 386.986 235.438 399.851 232.79 375.634C222.957 274.603 144.289 257.954 104.577 257.954H66V460.772H238.464C358.356 460.772 452.152 371.472 452.152 251.521C452.152 131.571 356.465 40 238.464 40Z" fill="url(#paint0_radial_8_208)" />
+      <path d="M238.464 40H66V236.007H104.577C220.688 236.007 232.79 158.437 232.79 121.733C232.79 108.867 243.38 108.867 243.38 121.733C251.318 236.701 356.35 245.457 365.527 246.223L365.542 246.224C374.619 246.981 382.561 251.521 365.542 254.548C253.592 264.765 243.758 364.282 243.38 375.634C243.002 386.986 235.438 399.851 232.79 375.634C222.957 274.603 144.289 257.954 104.577 257.954H66V460.772H238.464C358.356 460.772 452.152 371.472 452.152 251.521C452.152 131.571 356.465 40 238.464 40Z" stroke="#86997F" stroke-opacity="0.5" stroke-width="1.33156" />
+    </g>
+    <defs>
+      <filter id="filter0_d_8_208" x="60.7404" y="39.3342" width="396.671" height="431.358" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+        <feFlood flood-opacity="0" result="BackgroundImageFix" />
+        <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha" />
+        <feOffset dy="4.66045" />
+        <feGaussianBlur stdDeviation="2.29694" />
+        <feComposite in2="hardAlpha" operator="out" />
+        <feColorMatrix type="matrix" values="0 0 0 0 0.25464 0 0 0 0 0.285175 0 0 0 0 0.243391 0 0 0 0.1 0" />
+        <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_8_208" />
+        <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_8_208" result="shape" />
+      </filter>
+      <radialGradient id="paint0_radial_8_208" cx="0" cy="0" r="1" gradientTransform="matrix(399.011 555.102 -568.423 408.982 -11.6221 -34.9218)" gradientUnits="userSpaceOnUse">
+        <stop stop-color="#ADC77F" />
+        <stop offset="0.71903" stop-color="#517158" />
+        <stop offset="1" stop-color="#486954" />
+      </radialGradient>
+    </defs>
+  </svg>
+</template>

docs/content/1.guide/12.in-page-channel.md

@@ -54,31 +54,29 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-Functions are defined with `defineChannelFunction` — the same authoring shape as `defineRpcFunction` (`name`, `type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. Define each side's functions in that side's source files; the shared protocol file carries only types.
+Functions use the same authoring metadata as `defineRpcFunction` (`type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. The required `functions` object's keys are the function names, and it implements every function on that endpoint's protocol side. Each handler is contextually typed from its key and the corresponding function in the protocol. `defineChannelFunction` retains the named definition shape for lower-level authoring. Define each side's functions in that side's source files; the shared protocol file carries only types.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
 // inject/index.ts — runs in the user app's page
-import { createPageScriptChannel, defineChannelFunction } from 'devframe/in-page-channel'
+import { createPageScriptChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
 const channel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
-  functions: [
-    defineChannelFunction({
-      name: 'highlight',
+  functions: {
+    highlight: {
       type: 'event', // fire-and-forget
       jsonSerializable: true,
-      handler: (selector: string) => drawRing(document.querySelector(selector)),
-    }),
-    defineChannelFunction({
-      name: 'measure', // request/response (the default `query` type)
-      handler: (selector: string) => {
+      handler: selector => drawRing(document.querySelector(selector)),
+    },
+    measure: { // request/response (the default `query` type)
+      handler: (selector) => {
         const rect = document.querySelector(selector)!.getBoundingClientRect()
         return { width: rect.width, height: rect.height }
       },
-    }),
-  ],
+    },
+  },
 })
 
 channel.callEvent('flash', 'scanning…') // fans out to every connected panel
@@ -96,7 +94,14 @@ import type { MyChannelProtocol } from '../shared/protocol'
 import { connectPanelChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL })
+const channel = connectPanelChannel<MyChannelProtocol>({
+  name: MY_CHANNEL,
+  functions: {
+    flash: {
+      handler: message => showFlash(message),
+    },
+  },
+})
 
 channel.callEvent('highlight', '.hero') // buffered until connected
 const size = await channel.call('measure', '.hero')

docs/content/1.guide/14.security.md

@@ -67,6 +67,8 @@ Devtools ready — authenticate this browser: http://localhost:3000/#devframe_ot
 
 The code rides the URL **fragment** (`#devframe_otp=…`), which browsers never send to the server, keeping the single-use code out of access logs and `Referer` headers. `connectDevframe` reads it, exchanges it, and strips it from the URL. Because the link grants trust to whoever opens it within the code's lifetime, print it only to a trusted channel (the terminal).
 
+The link points at the **public origin**. A standalone dev server derives it from its own bound address; an owned listener uses that address regardless of any inbound `Host` header. A handler or middleware without an explicit `origin` derives one from a request only when the request's own origin is loopback or exactly matches an `allowedOrigins` entry — a raw inbound authority and forwarded headers are never trusted. Set `origin` explicitly for non-loopback handler deployments (behind a proxy, on a LAN, or on a public host) so the magic link always resolves to the address you intend.
+
 For your own auth UI, disable built-in handling with `otpParam: false`, then call `authenticateWithUrlOtp(rpc)` or `consumeOtpFromUrl()` from `devframe/client`.
 
 ## Practices for tools built on devframe

docs/content/1.guide/17.client-context.md

@@ -36,6 +36,29 @@ The context carries the [RPC client](/guide/client) (`rpc`) and the page's `clie
 
 `getDevframeClientContext()` returns the context anywhere; `undefined` before boot.
 
+### Tracking panel state
+
+`ctx.panel.state` is the current dock panel snapshot. It contains `state: 'open' | 'closed' | 'hidden'` and includes `selectedDockId` while a dock is selected. Subscribe to [`ctx.panel.events`](/references/events#client-context-events) for later changes:
+
+```ts
+import type { DockClientScriptContext } from '@devframes/hub/client'
+import { HUB_EVENTS } from '@devframes/hub/constants'
+
+export default function setup(context: DockClientScriptContext) {
+  const reportPanelState = (panelState: typeof context.panel.state) => {
+    void context.rpc.call('my-devframe:panel-state', panelState).catch(error => console.error(error))
+  }
+
+  reportPanelState(context.panel.state)
+  context.panel.events.on(
+    HUB_EVENTS.client.docksPanelStateChanged,
+    reportPanelState,
+  )
+}
+```
+
+The custom RPC keeps node-side reporting opt-in.
+
 ### Client-only docks
 
 A client runtime can register a dock local to the host page (unlike [node hub context](/guide/hub) docks synced via `devframe:docks`). `ctx.docks.register(entry)` — e.g. `type: 'custom-render'` with `renderer: { importFrom }` — returns a handle whose `update({ badge })` patches in place (id immutable) and `dispose()` removes it. One sharing a server dock's id overrides it locally; re-registering an owned id throws unless you pass `register(entry, true)`.

docs/content/1.guide/18.hub-initiate.md

@@ -53,7 +53,7 @@ interface DevframeHubUi {
 `@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + floating dock); its `setup(ctx)` publishes config to `ctx.staticConfig.ui` (`ConnectionMeta.configs.ui`):
 
 - **`viewer`** — set to `false` to disable the standalone viewer.
-- **`branding`** — rebrand the UI (logo, name, primary color). `background` accepts any CSS `background` value (color, gradient, image, or `transparent`) or `{ light, dark }` variants; omit it to keep the design default.
+- **`branding`** — rebrand the UI (logo, name, primary color). `background` accepts any CSS `background` value (color, gradient, image, or `transparent`) or `{ light, dark }` variants. These flat forms apply everywhere. Use `{ standalone, iframe? }` to specialize the framed viewer; an omitted `iframe` value falls back to `standalone`.
 - **`dockPreferences`** — dock-rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:
   - `'normal'` (default) — shows immediately.

docs/content/2.adapters/1.initiate.md

@@ -129,7 +129,7 @@ Fetch handlers only hand over `Request`s, so the host framework binds the RPC so
 
 ## Auth
 
-The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner once the public origin is known (the first request, or the `origin` option). Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
+The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner once the public origin is known — from the `origin` option, or derived from a request whose own origin is loopback or exactly matches an `allowedOrigins` entry. A non-loopback deployment (behind a proxy, on a LAN, on a public host) sets `origin` explicitly so the magic link resolves to the intended address; a raw inbound `Host` header and forwarded headers are never trusted. Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
 
 ## Relation to the other adapters
 

docs/content/5.add-ons/1.devframes/.navigation.yml

@@ -0,0 +1 @@
+title: Devframes