@revenexx/studio-shared 0.2.0 → 0.3.0

package/dist/runtime/components/Shared/RecordRailCard.d.vue.ts

@@ -0,0 +1,26 @@
+/**
+ * A card sized for the `RecordLayout` rail (PE-250).
+ *
+ * Same glass shell as the page cards, but on the rail's budget: `px-4 py-3`
+ * instead of `px-6 py-4`, a `text-xs` section label instead of a headline, and
+ * an optional right-aligned `#actions` (usually the link that jumps to the tab
+ * that owns the full thing). Use it so every rail across the studio stacks the
+ * same way instead of each page re-rolling its own `<section>`.
+ */
+type __VLS_Props = {
+    title?: string;
+};
+declare var __VLS_1: {}, __VLS_3: {};
+type __VLS_Slots = {} & {
+    actions?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Shared/RecordRailCard.vue

@@ -0,0 +1,20 @@
+<script setup>
+defineProps({
+  title: { type: String, required: false }
+});
+</script>
+
+<template>
+  <section class="overflow-hidden rounded-lg border border-gray-400/10 bg-white/60 outline-1 outline-white/30 backdrop-blur-sm">
+    <div
+      v-if="title || $slots.actions"
+      class="flex items-center justify-between gap-2 border-b border-black/[0.06] px-4 py-2.5"
+    >
+      <h3 class="truncate text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+        {{ title }}
+      </h3>
+      <slot name="actions" />
+    </div>
+    <slot />
+  </section>
+</template>

package/dist/runtime/components/Shared/RecordRailCard.vue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A card sized for the `RecordLayout` rail (PE-250).
+ *
+ * Same glass shell as the page cards, but on the rail's budget: `px-4 py-3`
+ * instead of `px-6 py-4`, a `text-xs` section label instead of a headline, and
+ * an optional right-aligned `#actions` (usually the link that jumps to the tab
+ * that owns the full thing). Use it so every rail across the studio stacks the
+ * same way instead of each page re-rolling its own `<section>`.
+ */
+type __VLS_Props = {
+    title?: string;
+};
+declare var __VLS_1: {}, __VLS_3: {};
+type __VLS_Slots = {} & {
+    actions?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Shared/SidebarNav.d.vue.ts

@@ -5,6 +5,11 @@
  * studio sidebar (Settings, Integrations, Commerce, Apps, …) renders
  * through this so spacing, active state, badges and "soon" tags stay
  * identical. Pass `sections`; use `#notice` for loading/empty hints.
+ *
+ * Items may declare `children`. Those are **tabs of the page the item opens**,
+ * not sub-navigation: every item is exactly one row, and it stays highlighted
+ * while the route is on any of its tabs. A surface that should stand on its
+ * own in the sidebar is declared as its own item.
  */
 import type { Component } from 'vue';
 import type { SidebarNavSection } from '../../types/nav.js';

package/dist/runtime/components/Shared/SidebarNav.vue

@@ -3,17 +3,14 @@
 </script>
 
 <script setup>
+import { sidebarItemKey } from "../../lib/sidebarNav";
+import SidebarNavLink from "./SidebarNavLink.vue";
 defineProps({
   title: { type: String, required: true },
   icon: { type: null, required: false },
   sections: { type: Array, required: true },
   minimal: { type: Boolean, required: false }
 });
-const route = useRoute();
-function isActive(item) {
-  if (item.exact) return route.path === item.to;
-  return route.path === item.to || route.path.startsWith(`${item.to}/`);
-}
 </script>
 
 <template>
@@ -37,28 +34,11 @@ function isActive(item) {
           </div>
         </div>
         <nav class="flex flex-col gap-0.5 px-2">
-          <NuxtLink
+          <SidebarNavLink
             v-for="item in section.items"
-            :key="item.to"
-            :to="item.to"
-            class="group flex items-center gap-2.5 rounded-md px-2 py-1.5 text-sm transition-colors hover:text-primary"
-            :class="[
-  isActive(item) ? 'bg-primary/10 text-[#0B0522] font-medium' : 'text-foreground/80 hover:bg-primary/5',
-  item.preview ? 'opacity-70' : ''
-]"
-          >
-            <component :is="item.icon" v-if="item.icon" :size="14" :stroke-width="2" class="shrink-0 text-foreground/60 group-hover:text-primary" />
-            <span class="flex-1 truncate flex items-center gap-1.5">
-              {{ item.label }}
-              <span
-                v-if="item.preview"
-                class="rounded bg-muted px-1 text-mono text-muted-foreground"
-                title="Coming soon"
-              >
-                soon
-              </span>
-            </span>
-          </NuxtLink>
+            :key="sidebarItemKey(item)"
+            :item="item"
+          />
         </nav>
       </template>
 

package/dist/runtime/components/Shared/SidebarNav.vue.d.ts

@@ -5,6 +5,11 @@
  * studio sidebar (Settings, Integrations, Commerce, Apps, …) renders
  * through this so spacing, active state, badges and "soon" tags stay
  * identical. Pass `sections`; use `#notice` for loading/empty hints.
+ *
+ * Items may declare `children`. Those are **tabs of the page the item opens**,
+ * not sub-navigation: every item is exactly one row, and it stays highlighted
+ * while the route is on any of its tabs. A surface that should stand on its
+ * own in the sidebar is declared as its own item.
  */
 import type { Component } from 'vue';
 import type { SidebarNavSection } from '../../types/nav.js';

package/dist/runtime/components/Shared/SidebarNavLink.d.vue.ts

@@ -0,0 +1,15 @@
+/**
+ * One row of a `SidebarNav` section — always exactly one link, never a group.
+ *
+ * An item's `children` are the **tabs of the page this row opens**, not rows
+ * of their own (see `lib/sidebarNav.ts`), so there is nothing to expand here:
+ * the row links to the item's route, or — for a pure container that nominates
+ * no landing page — to its first tab, and stays highlighted while the route is
+ * on any of them.
+ */
+import type { SidebarNavItem } from '../../types/nav.js';
+type __VLS_Props = {
+    item: SidebarNavItem;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Shared/SidebarNavLink.vue

@@ -0,0 +1,49 @@
+<script setup>
+import { sidebarItemIsCurrent, sidebarItemTarget } from "../../lib/sidebarNav";
+const props = defineProps({
+  item: { type: Object, required: true }
+});
+const t = useT();
+const route = useRoute();
+const target = computed(() => sidebarItemTarget(props.item));
+const current = computed(() => sidebarItemIsCurrent(props.item, route.path));
+const rowClass = computed(() => [
+  "group flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-sm transition-colors hover:text-primary",
+  current.value ? "bg-primary/10 text-[#0B0522] font-medium" : "text-foreground/80 hover:bg-primary/5",
+  props.item.preview ? "opacity-70" : ""
+]);
+</script>
+
+<template>
+  <NuxtLink v-if="target" :to="target" :class="rowClass">
+    <component :is="item.icon" v-if="item.icon" :size="14" :stroke-width="2" class="shrink-0 text-foreground/60 group-hover:text-primary" />
+    <span class="min-w-0 flex-1 truncate flex items-center gap-1.5">
+      {{ item.label }}
+      <span
+        v-if="item.preview"
+        class="rounded bg-muted px-1 text-mono text-muted-foreground"
+        :title="t('shared.nav.badge.comingsoon.tooltip')"
+      >
+        {{ t("shared.nav.badge.comingsoon.label") }}
+      </span>
+    </span>
+    <!--
+      What is waiting behind the entry. A count sits at the end of the row so
+      the labels stay left-aligned and scannable; a dot only says "something",
+      which is the honest rendering when the source cannot be counted.
+      Resolved upstream — an item with nothing pending carries no badge at all
+      rather than a zero, because a zero reads as a queue worth opening.
+    -->
+    <span
+      v-if="item.badge === 'dot'"
+      class="size-1.5 shrink-0 rounded-full bg-primary"
+      aria-hidden="true"
+    />
+    <span
+      v-else-if="item.badge !== null && item.badge !== void 0"
+      class="shrink-0 rounded-full bg-muted px-1.5 text-[11px] font-medium tabular-nums text-muted-foreground"
+    >
+      {{ item.badge }}
+    </span>
+  </NuxtLink>
+</template>

package/dist/runtime/components/Shared/SidebarNavLink.vue.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One row of a `SidebarNav` section — always exactly one link, never a group.
+ *
+ * An item's `children` are the **tabs of the page this row opens**, not rows
+ * of their own (see `lib/sidebarNav.ts`), so there is nothing to expand here:
+ * the row links to the item's route, or — for a pure container that nominates
+ * no landing page — to its first tab, and stays highlighted while the route is
+ * on any of them.
+ */
+import type { SidebarNavItem } from '../../types/nav.js';
+type __VLS_Props = {
+    item: SidebarNavItem;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Shared/Wizard.vue

@@ -7,6 +7,7 @@ const props = defineProps({
   busy: { type: Boolean, required: false, default: false }
 });
 const emit = defineEmits(["update:modelValue", "finish"]);
+const t = useT();
 const index = computed({
   get: () => props.modelValue,
   set: (v) => emit("update:modelValue", v)
@@ -40,7 +41,7 @@ function goTo(i) {
         @click="goTo(i)"
       >
         <div class="h-1 rounded-full transition-colors" :class="i <= index ? 'bg-primary' : 'bg-border'" />
-        <div class="mt-2 text-xs font-medium" :class="i <= index ? 'text-primary' : 'text-muted-foreground'">Step {{ i + 1 }}</div>
+        <div class="mt-2 text-xs font-medium" :class="i <= index ? 'text-primary' : 'text-muted-foreground'">{{ t("shared.wizard.step.label", { number: i + 1 }) }}</div>
         <div class="text-sm" :class="i <= index ? 'text-[#0B0522]' : 'text-muted-foreground'">{{ s.title }}</div>
       </div>
     </div>
@@ -53,9 +54,11 @@ function goTo(i) {
       <!-- Custom footer (e.g. multiple finish actions on a review step). Falls
            back to the standard Back / Next·Finish pair. -->
       <slot name="footer" :back="back" :next="next" :is-first="isFirst" :is-last="isLast" :can-advance="canAdvance" :busy="busy" :index="index">
-        <Button variant="ghost" :disabled="isFirst || busy" @click="back">Back</Button>
+        <Button variant="ghost" :disabled="isFirst || busy" @click="back">
+          {{ t("shared.wizard.action.back") }}
+        </Button>
         <Button :disabled="!canAdvance || busy" class="gap-1" @click="next">
-          {{ isLast ? "Finish" : "Next" }}
+          {{ isLast ? t("shared.wizard.action.finish") : t("shared.wizard.action.next") }}
         </Button>
       </slot>
     </div>

package/dist/runtime/composables/useListRail.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Open/closed state for a list surface's left rail, remembered per surface.
+ *
+ * The rail is a filter affordance, not content: an operator who collapsed it
+ * to give the table the full width expects it to stay collapsed on the next
+ * visit. Reads happen on mount (SSR-safe) and every change is written back;
+ * a browser without usable storage simply keeps the state for the session.
+ */
+export declare function useListRail(key: string, initial?: boolean): any;

package/dist/runtime/composables/useListRail.js

@@ -0,0 +1,19 @@
+export function useListRail(key, initial = true) {
+  const storageKey = `commerce.listRail.${key}`;
+  const open = ref(initial);
+  onMounted(() => {
+    try {
+      const raw = window.localStorage.getItem(storageKey);
+      if (raw != null) open.value = raw === "1";
+    } catch {
+    }
+  });
+  watch(open, (v) => {
+    try {
+      if (typeof window === "undefined") return;
+      window.localStorage.setItem(storageKey, v ? "1" : "0");
+    } catch {
+    }
+  });
+  return open;
+}

package/dist/runtime/composables/useMediaLibrary.d.ts

@@ -0,0 +1,41 @@
+import type { Ref } from 'vue';
+import type { StorageAsset, StorageFolder, StorageFolderNode, UploadProgress } from '../types/storage.js';
+/**
+ * Media library provider seam — the storage client behind the shared media
+ * components (`MediaUploader`, `MediaPickerDialog`, `MediaFolderTree`).
+ *
+ * Same shape as the `usePlatformAuth` / `usePlatformTenant` contract: the
+ * components never import a host's storage client, they call this. The
+ * standalone default below is inert (no assets, uploads report as failed), so a
+ * module host that hasn't wired Storage still renders the dialogs instead of
+ * crashing. The full cockpit overrides it at `app/composables/useMediaLibrary.ts`
+ * — an app-level auto-import beats this module-registered one (priority -1).
+ */
+export type { StorageAsset, StorageFolder, StorageFolderNode, UploadProgress };
+export interface MediaLibraryClient {
+    /** Assets in the current view. */
+    assets: Ref<StorageAsset[]>;
+    /** Folders nested by `parent_id`, each level sorted by name. */
+    folderTree: Ref<StorageFolderNode[]>;
+    currentFolderId: Ref<string | null>;
+    /** 'all' = every asset; 'unfiled' = folder-less; 'folder' = `currentFolderId`. */
+    currentView: Ref<'all' | 'unfiled' | 'folder'>;
+    currentFolder: Ref<StorageFolder | null>;
+    loadingAssets: Ref<boolean>;
+    hasMore: Ref<boolean>;
+    /** Load folders + the current view's assets. */
+    init: () => Promise<void>;
+    openFolder: (folderId: string) => Promise<void>;
+    showAllMedia: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    /** Upload a batch into `folderId`, reporting per-file progress. */
+    uploadMany: (files: File[], folderId?: string | null, onItem?: (index: number, progress: UploadProgress) => void) => Promise<{
+        created: number;
+        failed: number;
+    }>;
+    /** Displayable thumbnail URL, or null when the kind has no preview. */
+    thumbnailUrl: (asset: StorageAsset, size?: number) => string | null;
+    /** True while the asset is still being scanned/processed. */
+    isProcessing: (asset: StorageAsset) => boolean;
+}
+export declare function useMediaLibrary(): MediaLibraryClient;

package/dist/runtime/composables/useMediaLibrary.js

@@ -0,0 +1,36 @@
+import { computed, ref } from "vue";
+export function useMediaLibrary() {
+  const assets = ref([]);
+  const folderTree = ref([]);
+  const currentFolderId = ref(null);
+  const currentView = ref("all");
+  const currentFolder = computed(() => null);
+  const loadingAssets = ref(false);
+  const hasMore = ref(false);
+  const noop = async () => {
+  };
+  return {
+    assets,
+    folderTree,
+    currentFolderId,
+    currentView,
+    currentFolder,
+    loadingAssets,
+    hasMore,
+    init: noop,
+    openFolder: noop,
+    showAllMedia: noop,
+    loadMore: noop,
+    async uploadMany(files, _folderId, onItem) {
+      files.forEach((file, i) => onItem?.(i, {
+        name: file.name,
+        pct: 0,
+        status: "failed",
+        error: useT()("shared.media.uploader.error.nostorage")
+      }));
+      return { created: 0, failed: files.length };
+    },
+    thumbnailUrl: () => null,
+    isProcessing: () => false
+  };
+}

package/dist/runtime/composables/usePlatformAuth.d.ts

@@ -1,3 +1,4 @@
+import type { Ref } from 'vue';
 /**
  * Platform auth provider — the seam that lets a studio surface run either
  * inside the full cockpit or standalone.
@@ -13,5 +14,22 @@
  */
 export interface PlatformAuth {
     getToken: () => Promise<string | null>;
+    /**
+     * Whether a token is available NOW, as a reactive flag. OPTIONAL, because the
+     * standalone default below has nothing to report — a value in `localStorage` is
+     * either there or not, with no moment at which it becomes there.
+     *
+     * It exists for the hosts where `getToken()` legitimately answers null for a
+     * while and then starts working: the cockpit's override refreshes through
+     * `useConsoleAuth`, which backs off for 15s after a failed refresh and returns
+     * null for the duration. A consumer that only reacts to something ELSE changing
+     * — `usePlatformTalkback` watched the tenant slug — never retries and stays
+     * dead for the life of the tab.
+     *
+     * Deliberately a flag rather than the token itself: nothing outside the auth
+     * seam should hold a token it did not just ask for, and a stale one in a `ref`
+     * is exactly how that happens.
+     */
+    ready?: Readonly<Ref<boolean>>;
 }
 export declare function usePlatformAuth(): PlatformAuth;

package/dist/runtime/composables/usePlatformTalkback.d.ts

@@ -0,0 +1,29 @@
+import type { ShallowRef } from 'vue';
+import type { Talkback } from '@revenexx/talkback-js';
+/**
+ * Platform realtime provider — the third seam beside `usePlatformAuth` and
+ * `usePlatformTenant`, and it composes both of them.
+ *
+ * A studio module never builds a Talkback client itself: it calls
+ * `useTalkbackTopic()` / `useTalkbackResource()` and this decides whether there
+ * is a connection behind them. One client for the whole application — a second
+ * `createTalkback` would open a second WebSocket and mint its own connection
+ * token.
+ *
+ * OFF IS A FIRST-CLASS STATE. An empty `talkbackHost` means no client is built,
+ * neither `@revenexx/talkback-js` nor `centrifuge` is loaded, and the channel
+ * composables become no-ops — so a call site needs no guard and a host that has
+ * no realtime stack is not half-connected. That is also the production gate: the
+ * edge has not been shown to pass a WebSocket upgrade yet (PE-382 T0.2).
+ */
+export interface PlatformTalkback {
+    /**
+     * The client, or `null` while it is still loading or realtime is off.
+     * Reactive: the client arrives after a dynamic import, so a component that
+     * rendered first has to be able to pick it up.
+     */
+    talkback: ShallowRef<Talkback | null>;
+    /** Whether this host has realtime configured at all. */
+    enabled: boolean;
+}
+export declare function usePlatformTalkback(): PlatformTalkback;

package/dist/runtime/composables/usePlatformTalkback.js

@@ -0,0 +1,54 @@
+import { watch } from "vue";
+import { createPlatformTalkback, setTalkback, talkbackRef } from "../lib/talkback.js";
+function withAppBase(baseURL, path) {
+  if (/^https?:\/\//.test(path)) return path;
+  const base = (baseURL || "/").replace(/\/+$/, "");
+  return `${base}/${path.replace(/^\/+/, "")}`;
+}
+let started = false;
+export function usePlatformTalkback() {
+  const config = useRuntimeConfig();
+  const host = String(config.public.talkbackHost || "");
+  const enabled = Boolean(host);
+  if (enabled && import.meta.client && !started) {
+    started = true;
+    const { getToken, ready: authReady } = usePlatformAuth();
+    const { slug, load } = usePlatformTenant();
+    const baseURL = String(config.app?.baseURL || "/");
+    const facade = host.replace(/\/+$/, "");
+    const tokenEndpoint = withAppBase(baseURL, String(config.public.talkbackTokenEndpoint || `${facade}/v1/tokens`));
+    const subscriptionTokenEndpoint = withAppBase(baseURL, String(config.public.talkbackSubscriptionTokenEndpoint || `${facade}/v1/subscription-tokens`));
+    const start = (async () => {
+      const tb = await createPlatformTalkback({
+        host,
+        tokenEndpoint,
+        subscriptionTokenEndpoint,
+        tenant: () => slug.value ?? "",
+        getToken
+      });
+      setTalkback(tb);
+      let applied = null;
+      async function sync() {
+        if (!slug.value) {
+          try {
+            await load();
+          } catch {
+          }
+        }
+        const token = await getToken();
+        const next = slug.value && token ? slug.value : null;
+        if (next === applied) return;
+        tb.disconnect();
+        applied = next;
+        if (next) tb.connect();
+      }
+      const inputs = authReady ? [slug, authReady] : [slug];
+      watch(inputs, () => void sync(), { immediate: true });
+    })();
+    void start.catch((error) => {
+      if (!talkbackRef().value) started = false;
+      console.warn("[studio-shared] talkback failed to start", error);
+    });
+  }
+  return { talkback: talkbackRef(), enabled };
+}

package/dist/runtime/composables/useT.d.ts

@@ -0,0 +1,11 @@
+import type { ComputedRef } from 'vue';
+import type { Translate } from '../lib/i18nBridge.js';
+export declare function useT(): Translate;
+/**
+ * The host's current UI locale (`'en'` when the host has no i18n).
+ *
+ * This is the INTERFACE language, not a content locale: it says which language
+ * the chrome is in, never which locale of a `labels` jsonb to show. For the
+ * latter see `useTenantLocales()` in `@revenexx/studio-commerce`.
+ */
+export declare function useUiLocale(): ComputedRef<string>;

package/dist/runtime/composables/useT.js

@@ -0,0 +1,8 @@
+import { computed } from "vue";
+import { currentLocale, translate } from "../lib/i18nBridge.js";
+export function useT() {
+  return translate;
+}
+export function useUiLocale() {
+  return computed(() => currentLocale());
+}

package/dist/runtime/composables/useTalkbackChannels.d.ts

@@ -0,0 +1,78 @@
+import type { ComputedRef } from 'vue';
+import type { EnvelopeListener, RawListener, ResyncContext } from '@revenexx/talkback-js';
+import type { MaybeRefOrGetter } from '@revenexx/talkback-js/vue';
+/**
+ * The five channel composables, re-exported through this package so a studio
+ * module can subscribe with a bare name and carry no Talkback dependency of its
+ * own — the same contract `usePlatformAuth` / `usePlatformTenant` already have.
+ *
+ * THREE THINGS THESE WRAPPERS ADD, and each is a bug without them:
+ *
+ * 1. **The client is passed explicitly, never injected.** talkback-js's
+ *    `useTalkback()` reads a module-PRIVATE `Symbol`, so two copies of the
+ *    package are two different keys: it throws inside a studio module while the
+ *    host looks healthy. Its `talkback` option exists for exactly this, and
+ *    using it means no consumer has to know a plugin ran in the right order.
+ *
+ * 2. **They tolerate a client that does not exist yet.** The client arrives
+ *    after a dynamic import, so any component that rendered first would
+ *    otherwise subscribe to nothing and never retry. The delegate runs in a
+ *    child `effectScope` that is created when the client appears and stopped
+ *    with the caller's scope — which is also what gives the delegate's own
+ *    `onScopeDispose(release)` a scope to bind to.
+ *
+ * 3. **`channel` is actually reactive.** Up to and including
+ *    `@revenexx/talkback-js@0.1.3`, `ChannelSubscription.channel` is
+ *    `{ value: null }` cast to a `Ref` — `ref` is never imported, so `isRef()`
+ *    is false and a template binding never updates. Fixed upstream in
+ *    talkback-js#11 but unreleased; this wrapper can be simplified to a
+ *    pass-through once that ships.
+ *
+ * With realtime off (`talkbackHost` empty) every one of these is a no-op that
+ * reports a null channel, so a call site needs no `if (enabled)`.
+ */
+/** Re-exported so a consumer types a ref-able argument without importing talkback-js. */
+export type TalkbackMaybeRef<T> = MaybeRefOrGetter<T>;
+export interface TalkbackChannelOptions {
+    /** One action, or several. Omit to receive every action on the channel. */
+    on?: string | readonly string[];
+    /** Called for each matching envelope. Events are refetch signals, not state. */
+    handler?: EnvelopeListener;
+    /** Every publication, envelope or not — how a `stream:` channel is read. */
+    raw?: RawListener;
+    /** The recovery buffer could not close the gap: refetch over HTTP. */
+    onResync?: (ctx: ResyncContext) => void;
+    /** Skip subscribing, e.g. while a route parameter is still empty. */
+    enabled?: TalkbackMaybeRef<boolean>;
+}
+export interface TalkbackChannel {
+    /** The currently subscribed channel, or null when nothing is subscribed. */
+    channel: ComputedRef<string | null>;
+    /** Releases early. Called automatically when the calling scope is disposed. */
+    stop: () => void;
+}
+/**
+ * The ACTION channel for a topic — a grid watching every instance of a kind.
+ *
+ * THE TOPIC INCLUDES THE ACTION, and one action is one channel (Centrifugo has
+ * no wildcards), so a grid watching three actions takes three calls:
+ *
+ * ```ts
+ * for (const action of ['started', 'finished', 'failed'] as const) {
+ *   useTalkbackTopic(`revenexx.integrations.run.${action}`, { handler: () => load(true) })
+ * }
+ * ```
+ */
+export declare function useTalkbackTopic(topic: TalkbackMaybeRef<string>, options?: TalkbackChannelOptions): TalkbackChannel;
+/**
+ * The RESOURCE channel — one detail view, every action on it. The id may be a
+ * ref or a getter, and the subscription follows it, releasing the old channel
+ * before taking the new one.
+ */
+export declare function useTalkbackResource(topic: TalkbackMaybeRef<string>, topicId: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;
+/** The signed-in user's own channel — notifications and toasts. */
+export declare function useTalkbackUser(options?: TalkbackChannelOptions): TalkbackChannel;
+/** A `stream:` channel. `onResync` fires on EVERY subscribe here — it keeps no history. */
+export declare function useTalkbackStream(streamId: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;
+/** Who else is looking at this resource. */
+export declare function useTalkbackPresence(vendor: TalkbackMaybeRef<string>, app: TalkbackMaybeRef<string>, entity: TalkbackMaybeRef<string>, id?: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;

package/dist/runtime/composables/useTalkbackChannels.js

@@ -0,0 +1,52 @@
+import { computed, effectScope, onScopeDispose, ref, shallowRef, watch } from "vue";
+import { talkbackRef } from "../lib/talkback.js";
+function useDelegate(subscribe) {
+  const client = talkbackRef();
+  const name = ref(null);
+  const scope = shallowRef(null);
+  function stop() {
+    scope.value?.stop();
+    scope.value = null;
+    name.value = null;
+  }
+  const unwatch = watch(client, (tb) => {
+    stop();
+    if (!tb) return;
+    const child = effectScope();
+    scope.value = child;
+    void (async () => {
+      const vue = await import("@revenexx/talkback-js/vue");
+      if (scope.value !== child) return;
+      child.run(() => {
+        let sub;
+        try {
+          sub = subscribe(vue, tb);
+        } catch {
+          name.value = null;
+          return;
+        }
+        watch(() => sub.channel.value, (v) => name.value = v, { immediate: true, flush: "sync" });
+      });
+    })();
+  }, { immediate: true });
+  onScopeDispose(() => {
+    unwatch();
+    stop();
+  });
+  return { channel: computed(() => name.value), stop };
+}
+export function useTalkbackTopic(topic, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackTopic(topic, { ...options, talkback: tb }));
+}
+export function useTalkbackResource(topic, topicId, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackResource(topic, topicId, { ...options, talkback: tb }));
+}
+export function useTalkbackUser(options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackUser({ ...options, talkback: tb }));
+}
+export function useTalkbackStream(streamId, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackStream(streamId, { ...options, talkback: tb }));
+}
+export function useTalkbackPresence(vendor, app, entity, id = () => null, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackPresence(vendor, app, entity, id, { ...options, talkback: tb }));
+}