@antelopejs/dms 0.0.1

package/frontend-vue/layers/dms-layout/app/composables/useCommandPaletteSources.ts

@@ -0,0 +1,171 @@
+import type {
+  CommandPaletteGroup,
+  CommandPaletteItem,
+  DashboardSearchProps,
+} from "@nuxt/ui";
+
+/**
+ * A contributor of command-palette (Ctrl/Cmd+K) groups. Like
+ * {@link HeaderAction}, sources live in keyed DMS app state so any module's
+ * layer can register one without a build-time dependency on this layer.
+ *
+ * Because sources carry callables (`groups`, item `onSelect`), they must be
+ * registered from CLIENT context (a `.client` plugin or component setup):
+ * function values are not part of the SSR payload, so a server-side
+ * registration would arrive on the client stripped. `useCommandPaletteGroups`
+ * defensively drops such entries, so a stray server-side registration
+ * degrades to "commands not shown" rather than a runtime crash.
+ */
+export interface CommandPaletteSource {
+  /** Unique key: dedup on `register` (upsert) and target of `unregister`. */
+  id: string;
+  /**
+   * Position of this source's groups relative to other sources, ascending.
+   * Defaults to `100`; sources sharing the same effective order preserve
+   * registration order. Applies to the initial (empty-search) view — while
+   * the user types, the palette reorders groups by match relevance.
+   */
+  order?: number;
+  /**
+   * Builds the groups this source contributes. Evaluated inside a `computed`,
+   * so any reactive state read here updates the palette automatically.
+   * Return `[]` when there is nothing to show. Prefix group ids with the
+   * source id: ids are global to the palette and a collision silently merges
+   * the colliding groups' items under the first group's header.
+   */
+  groups: () => CommandPaletteGroup[];
+}
+
+const COMMAND_PALETTE_SOURCES_STATE_KEY = "dms:command-palette-sources";
+const DEFAULT_SOURCE_ORDER = 100;
+
+/**
+ * Item field the palette search indexes but never renders. Sources set it to
+ * make an entry reachable through text that has no place on the item itself —
+ * a page description, alternate wordings — while `label` and `suffix` keep
+ * driving what the user sees.
+ */
+export const COMMAND_PALETTE_SEARCH_TEXT_KEY = "searchText";
+
+const SEARCH_TEXT_WEIGHT = 0.3;
+
+/**
+ * Fuse configuration handed to `UDashboardSearch`, merged by `defu` into the
+ * component's own defaults. That merge concatenates `keys`, so listing the
+ * built-in `label` and `suffix` here would index them twice: only the extra key
+ * belongs in this list. Its low weight keeps a page matched on its search text
+ * alone behind pages whose title or breadcrumb matches.
+ */
+export const COMMAND_PALETTE_FUSE_OPTIONS: DashboardSearchProps["fuse"] = {
+  fuseOptions: {
+    keys: [
+      { name: COMMAND_PALETTE_SEARCH_TEXT_KEY, weight: SEARCH_TEXT_WEIGHT },
+    ],
+  },
+};
+
+interface CommandPaletteSearchMatch {
+  key?: string;
+}
+
+function isSearchTextMatch(match: CommandPaletteSearchMatch): boolean {
+  return match.key === COMMAND_PALETTE_SEARCH_TEXT_KEY;
+}
+
+function withoutSearchTextMatches(
+  item: CommandPaletteItem,
+): CommandPaletteItem {
+  const matches = item.matches as CommandPaletteSearchMatch[] | undefined;
+  if (!matches?.some(isSearchTextMatch)) {
+    return item;
+  }
+
+  return {
+    ...item,
+    matches: matches.filter((match) => !isSearchTextMatch(match)),
+  };
+}
+
+/**
+ * Drops {@link COMMAND_PALETTE_SEARCH_TEXT_KEY} matches from a group's items
+ * before the palette renders them. Nuxt UI displays the first match whose key
+ * is not the label as the item suffix, so a hit on the hidden search text would
+ * replace the breadcrumb with an excerpt of that text.
+ */
+export function hideSearchTextMatches(
+  group: CommandPaletteGroup,
+): CommandPaletteGroup {
+  const { postFilter } = group;
+
+  return {
+    ...group,
+    postFilter: (searchTerm, items) =>
+      (postFilter?.(searchTerm, items) ?? items).map(withoutSearchTextMatches),
+  };
+}
+
+function sourceOrder(source: CommandPaletteSource): number {
+  return source.order ?? DEFAULT_SOURCE_ORDER;
+}
+
+function isSourceRenderable(source: CommandPaletteSource): boolean {
+  return typeof source.groups === "function";
+}
+
+function useCommandPaletteSourceState() {
+  return useDmsState<CommandPaletteSource[]>(
+    COMMAND_PALETTE_SOURCES_STATE_KEY,
+    () => [],
+  );
+}
+
+export function registerCommandPaletteSource(
+  source: CommandPaletteSource,
+): void {
+  const sources = useCommandPaletteSourceState();
+  const next = sources.value.filter((entry) => entry.id !== source.id);
+  next.push(source);
+  sources.value = next;
+}
+
+export function unregisterCommandPaletteSource(id: string): void {
+  const sources = useCommandPaletteSourceState();
+  sources.value = sources.value.filter((entry) => entry.id !== id);
+}
+
+function safeSourceGroups(source: CommandPaletteSource): CommandPaletteGroup[] {
+  try {
+    return source.groups();
+  } catch (error) {
+    console.error(
+      `[command-palette] source "${source.id}" failed to build groups`,
+      error,
+    );
+    return [];
+  }
+}
+
+/**
+ * Aggregated groups from every registered {@link CommandPaletteSource},
+ * ordered by source `order`. A source whose `groups` getter throws is
+ * skipped so it cannot take the other sources down with it. Every group goes
+ * through {@link hideSearchTextMatches}, so a source can set
+ * {@link COMMAND_PALETTE_SEARCH_TEXT_KEY} without minding the rendering. Fed to
+ * `UDashboardSearch` by the DMS; consumers normally only need
+ * `registerCommandPaletteSource`.
+ */
+export function useCommandPaletteGroups() {
+  const sources = useCommandPaletteSourceState();
+
+  const orderedSources = computed<CommandPaletteSource[]>(() =>
+    sources.value
+      .filter(isSourceRenderable)
+      .sort((a, b) => sourceOrder(a) - sourceOrder(b)),
+  );
+
+  const groups = computed<CommandPaletteGroup[]>(() =>
+    orderedSources.value.flatMap(safeSourceGroups).map(hideSearchTextMatches),
+  );
+
+  return { groups };
+}

package/frontend-vue/layers/dms-layout/app/composables/useDevReload.ts

@@ -0,0 +1,401 @@
+const DEV_RELOAD_STATE_KEY = "dms:dev-reloading";
+const DEV_RELOAD_HOLDER_KEY = "__dmsDevReload";
+
+const ROUTE_READY_POLL_INTERVAL_MS = 150;
+const ROUTE_READY_TIMEOUT_MS = 15000;
+const ROUTE_READY_INITIAL_DELAY_MS = 150;
+// Outside dev nothing in this file re-fetches the site layout, so a long wait
+// could only ever stall the caller. Cap it: either a refresh started elsewhere
+// lands within the moment, or the answer is "not served".
+const PRODUCTION_ROUTE_WAIT_MS = 2000;
+// Comfortably past the route-ready deadline: this only catches a refresh that
+// never settles at all, not a slow one.
+const RELOAD_FLAG_MAX_MS = ROUTE_READY_TIMEOUT_MS + 5000;
+
+/**
+ * Whether a dev hot reload is in flight. A module re-registers its pages one at
+ * a time, so the page the user is on can be missing for a moment. Raising a 404
+ * then would flash an error the reload is about to fix, so the renderer holds
+ * off while this is true.
+ *
+ * Internal state: it drives the 404 suppression and nothing else. It is never
+ * rendered — the current page stays mounted and the new layout is applied in
+ * place, so the add/remove/update animations play as usual.
+ */
+export const useDevReloading = () =>
+  useDmsState<boolean>(DEV_RELOAD_STATE_KEY, () => false);
+
+/** Everything the coordinator needs from the surrounding DMS app. */
+export interface DevReloadDeps {
+  /** True when the committed site layout already serves `path`. */
+  isRouteKnown: (path: string) => boolean;
+  /**
+   * Fetch a fresh site layout and commit it only if it serves `path`; false
+   * while the route is still missing. Dev-only, see `useSiteLayout`.
+   */
+  probeAndCommitRoute: (path: string) => Promise<boolean>;
+  /** Commit whatever the backend serves now, route present or not. */
+  commitLayout: () => Promise<void>;
+  /** Refresh everything hanging off the committed layout, for `path`. */
+  refreshDerived: (path: string) => Promise<void>;
+  /** Drop the transient 404 raised while `path` was unregistered. */
+  clearTransient404: (path: string) => void;
+  /** The route the user is on right now. */
+  currentPath: () => string;
+  setReloading: (value: boolean) => void;
+  isDev: boolean;
+  /** Clock and sleep, injected so the loops can be driven in a test. */
+  delay: (ms: number) => Promise<void>;
+  now: () => number;
+}
+
+export interface AwaitRouteOptions {
+  /** Give up after this many milliseconds. Defaults to 15000. */
+  timeoutMs?: number;
+}
+
+export interface DevReloadCoordinator {
+  /**
+   * Run a soft refresh for `path` (default: the current route) and resolve with
+   * whether the committed layout serves it. Coalesces: a call made while a
+   * refresh is in flight joins it and books exactly one trailing re-run.
+   */
+  requestRefresh: (path?: string) => Promise<boolean>;
+  awaitRoute: (path: string, options?: AwaitRouteOptions) => Promise<boolean>;
+  settled: () => Promise<void>;
+}
+
+/** The one polling loop. `step` decides what "ready" means for its caller. */
+async function pollUntil(
+  step: () => boolean | Promise<boolean>,
+  deadline: number,
+  timing: Pick<DevReloadDeps, "delay" | "now">,
+): Promise<boolean> {
+  for (;;) {
+    if (await step()) return true;
+    if (timing.now() >= deadline) return false;
+    await timing.delay(ROUTE_READY_POLL_INTERVAL_MS);
+  }
+}
+
+// Hold the refresh until the route actually resolves in a freshly fetched
+// layout, then commit THAT layout atomically. A hot reload re-registers modules
+// one at a time (and can do so more than once in quick succession), so the
+// backend can be reachable while the page is momentarily unregistered.
+// Committing then would drop the page and 404 it. probeAndCommitRoute fetches
+// once and only commits if the route is present, so the check and the commit
+// cannot be split by a second unregister burst. If the route never comes back
+// (page genuinely deleted), we time out and commit whatever the backend now
+// has, letting the page component handle the 404.
+async function commitWhenRouteReady(
+  path: string,
+  deadline: number,
+  deps: DevReloadDeps,
+  timing: Pick<DevReloadDeps, "delay" | "now">,
+): Promise<boolean> {
+  await timing.delay(ROUTE_READY_INITIAL_DELAY_MS);
+  const committed = await pollUntil(
+    () => deps.probeAndCommitRoute(path),
+    deadline,
+    timing,
+  );
+  if (!committed) {
+    console.warn(
+      "[dms-dev-reload] Route readiness timed out, refreshing anyway",
+    );
+  }
+  return committed;
+}
+
+async function softRefresh(
+  path: string,
+  deadline: number,
+  deps: DevReloadDeps,
+  timing: Pick<DevReloadDeps, "delay" | "now">,
+): Promise<boolean> {
+  const committed = await commitWhenRouteReady(path, deadline, deps, timing);
+  if (!committed) await deps.commitLayout();
+  await deps.refreshDerived(path);
+  if (committed) deps.clearTransient404(path);
+  return committed;
+}
+
+/**
+ * The single dev-reload mechanism, with its dependencies passed in so it can be
+ * exercised without a DMS app runtime.
+ *
+ * Both entry points — the SSE `reload` event and a module's `awaitRoute` —
+ * funnel through the same route-readiness loop and the same in-flight refresh,
+ * so a module never polls the layout on its own and never races the plugin with
+ * a second fetch loop.
+ */
+/**
+ * Everything the loops below share: the app they drive, the clock they read,
+ * and the one in-flight pass they coalesce on.
+ */
+interface CoordinatorState {
+  deps: DevReloadDeps;
+  refreshing: Promise<boolean> | null;
+  /**
+   * A reload event can arrive while a previous refresh is still polling for its
+   * route. Rather than drop it, remember that one more pass is owed and run it
+   * once the in-flight pass settles -- re-reading the current route at that
+   * point, since the user may have navigated meanwhile (polling a stale
+   * captured path would waste the whole timeout). Coalesces a burst into a
+   * single trailing re-run.
+   */
+  rerunPending: boolean;
+}
+
+function handOverToRerun(state: CoordinatorState): boolean {
+  if (!state.rerunPending) return false;
+  state.rerunPending = false;
+  // The re-run owns the reloading flag from here.
+  void runRefresh(
+    state,
+    state.deps.currentPath(),
+    state.deps.now() + ROUTE_READY_TIMEOUT_MS,
+  );
+  return true;
+}
+
+function runRefresh(
+  state: CoordinatorState,
+  path: string,
+  deadline: number,
+): Promise<boolean> {
+  const { deps } = state;
+  deps.setReloading(true);
+  // A refresh that never settles would leave the flag set, and the flag
+  // suppresses 404s -- every later missing page would come up blank for the
+  // rest of the session. Release it on a deadline regardless.
+  const release = setTimeout(() => {
+    deps.setReloading(false);
+  }, RELOAD_FLAG_MAX_MS);
+  const started: Promise<boolean> = softRefresh(path, deadline, deps, deps)
+    .catch((err: unknown) => {
+      console.error("[dms-dev-reload] Soft refresh failed:", err);
+      return false;
+    })
+    .finally(() => {
+      clearTimeout(release);
+      if (state.refreshing === started) state.refreshing = null;
+      if (!handOverToRerun(state)) deps.setReloading(false);
+    });
+  state.refreshing = started;
+  return started;
+}
+
+function requestRefresh(
+  state: CoordinatorState,
+  path?: string,
+): Promise<boolean> {
+  if (state.refreshing) {
+    state.rerunPending = true;
+    return state.refreshing;
+  }
+  const { deps } = state;
+  return runRefresh(
+    state,
+    path ?? deps.currentPath(),
+    deps.now() + ROUTE_READY_TIMEOUT_MS,
+  );
+}
+
+/**
+ * Joins passes until none is running or `stop` says so. A settling refresh may
+ * hand over to a booked re-run, which is still "in flight"; the identity check
+ * makes the loop terminate as soon as no new pass is started.
+ */
+async function joinInFlight(
+  state: CoordinatorState,
+  stop: () => boolean,
+): Promise<void> {
+  let joined: Promise<boolean> | null = null;
+  while (state.refreshing && state.refreshing !== joined && !stop()) {
+    joined = state.refreshing;
+    await joined.catch(() => undefined);
+  }
+}
+
+function settled(state: CoordinatorState): Promise<void> {
+  return joinInFlight(state, () => false);
+}
+
+function awaitRouteDeadline(
+  deps: DevReloadDeps,
+  options?: AwaitRouteOptions,
+): number {
+  const timeoutMs = options?.timeoutMs ?? ROUTE_READY_TIMEOUT_MS;
+  return (
+    deps.now() +
+    (deps.isDev ? timeoutMs : Math.min(timeoutMs, PRODUCTION_ROUTE_WAIT_MS))
+  );
+}
+
+async function awaitRoute(
+  state: CoordinatorState,
+  path: string,
+  options?: AwaitRouteOptions,
+): Promise<boolean> {
+  const { deps } = state;
+  if (deps.isRouteKnown(path)) return true;
+  const deadline = awaitRouteDeadline(deps, options);
+
+  // A refresh already in flight is re-committing the whole layout, which may be
+  // all this caller needs; join it instead of racing it with a second fetch
+  // loop.
+  await joinInFlight(
+    state,
+    () => deps.isRouteKnown(path) || deps.now() >= deadline,
+  );
+  if (deps.isRouteKnown(path)) return true;
+
+  // Outside dev there is no reload stream and probeAndCommitRoute is a no-op,
+  // so the only thing that can bring the route in is a refresh driven
+  // elsewhere. Watch the committed layout for a moment, then answer.
+  if (!deps.isDev) {
+    return pollUntil(() => deps.isRouteKnown(path), deadline, deps);
+  }
+
+  // Deadline spent waiting on someone else's pass.
+  if (state.refreshing || deps.now() >= deadline) return deps.isRouteKnown(path);
+
+  const committed = await runRefresh(state, path, deadline);
+  // A trailing re-run booked over ours may be the one that brought the route
+  // in, so re-read the committed layout rather than trusting our own answer.
+  return committed || deps.isRouteKnown(path);
+}
+
+/**
+ * The single dev-reload mechanism, with its dependencies passed in so it can be
+ * exercised without a DMS app runtime.
+ *
+ * Both entry points -- the SSE `reload` event and a module's `awaitRoute` --
+ * funnel through the same route-readiness loop and the same in-flight refresh,
+ * so a module never polls the layout on its own and never races the plugin with
+ * a second fetch loop.
+ */
+export function createDevReloadCoordinator(
+  deps: DevReloadDeps,
+): DevReloadCoordinator {
+  const state: CoordinatorState = {
+    deps,
+    refreshing: null,
+    rerunPending: false,
+  };
+  return {
+    requestRefresh: (path?: string) => requestRefresh(state, path),
+    awaitRoute: (path: string, options?: AwaitRouteOptions) =>
+      awaitRoute(state, path, options),
+    settled: () => settled(state),
+  };
+}
+
+// Refresh everything that hangs off the site layout, AFTER the layout itself
+// has been (re)committed for the current route. Kept separate from the layout
+// commit so the commit can stay atomic with its route check (see
+// probeAndCommitRoute) — the 404-prone part was committing the layout, not this.
+async function postLayoutRefresh(currentRoutePath: string): Promise<void> {
+  const permissions = usePermissions();
+  // fetchPermissions() refetches and swaps the set atomically, so there is no
+  // need to clear() first — clearing would briefly empty permissions and flash
+  // permission-gated UI.
+  await permissions.fetchPermissions();
+  await refreshDmsData(currentRoutePath);
+  await refreshDmsData(`layout-${currentRoutePath}`);
+}
+
+interface DevReloadHolder {
+  coordinator: DevReloadCoordinator;
+  reloading: Ref<boolean>;
+}
+
+/**
+ * The app-wide coordinator. Held on the DMS app rather than in a per-call ref:
+ * every caller has to see the same in-flight refresh, or they would each run
+ * their own fetch loop and the older answer could land last. Same holder as the
+ * site layout's in-flight fetch (see `useSiteLayout`).
+ *
+ * Core-internal — module frontends use {@link useDmsDevReload}.
+ */
+export function useDevReloadHolder(): DevReloadHolder {
+  const dmsApp = useDmsApp() as unknown as Record<PropertyKey, unknown>;
+  const existing = dmsApp[DEV_RELOAD_HOLDER_KEY] as DevReloadHolder | undefined;
+  if (existing) return existing;
+
+  // Outside dev the flag is a plain ref rather than shared state, so the key
+  // never reaches a production SSR payload.
+  const reloading = import.meta.env.DEV ? useDevReloading() : ref(false);
+  const siteLayout = useSiteLayout();
+  const router = useDmsRouter();
+  const currentError = useError();
+
+  const coordinator = createDevReloadCoordinator({
+    isDev: import.meta.env.DEV,
+    currentPath: () => router.currentRoute.value.path,
+    isRouteKnown: (path) => siteLayout.findMatchingRoute(path) !== null,
+    probeAndCommitRoute: (path) => siteLayout.probeAndCommitRoute(path),
+    commitLayout: () => siteLayout.refresh(),
+    refreshDerived: postLayoutRefresh,
+    // Clear the transient 404 [...slug].vue raised while the route was briefly
+    // unregistered, so the page re-renders once the route is committed again.
+    // Only when the user is still on the path we recovered — otherwise they
+    // navigated to a genuinely missing route meanwhile and that 404 must stand.
+    clearTransient404: (recoveredPath) => {
+      if (router.currentRoute.value.path !== recoveredPath) return;
+      const err = currentError.value;
+      if (!err || err.statusCode !== HTTP_NOT_FOUND) return;
+      void clearError();
+    },
+    setReloading: (value) => {
+      reloading.value = value;
+    },
+    now: () => Date.now(),
+    delay: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+  });
+
+  const holder: DevReloadHolder = { coordinator, reloading };
+  dmsApp[DEV_RELOAD_HOLDER_KEY] = holder;
+  return holder;
+}
+
+export interface DmsDevReload {
+  /**
+   * Whether a dev reload is in flight. Internal state — never render it: the
+   * point of this mechanism is that a reload is invisible.
+   */
+  reloading: Readonly<Ref<boolean>>;
+  /** Resolves once no refresh is in flight. */
+  settled: () => Promise<void>;
+  /**
+   * Resolves `true` once the committed site layout serves `path`, `false` on
+   * timeout (default 15000 ms).
+   */
+  awaitRoute: (path: string, options?: AwaitRouteOptions) => Promise<boolean>;
+}
+
+/**
+ * Wait for the DMS to catch up with a backend change, from a module frontend.
+ *
+ * Writing a page from the no-code builder or the AI chatbox reloads the backend
+ * module, which re-registers its pages one at a time; navigating straight away
+ * would land on a route the site layout does not serve yet. `awaitRoute` holds
+ * until it does, sharing the core's refresh rather than polling the layout
+ * state on its own.
+ *
+ * ```ts
+ * const { awaitRoute } = useDmsDevReload();
+ * await createPage(path);
+ * await awaitRoute(path);
+ * await navigateDms(path);
+ * ```
+ */
+export const useDmsDevReload = (): DmsDevReload => {
+  const { coordinator, reloading } = useDevReloadHolder();
+  return {
+    reloading,
+    settled: coordinator.settled,
+    awaitRoute: coordinator.awaitRoute,
+  };
+};

package/frontend-vue/layers/dms-layout/app/composables/useFooterLinks.ts

@@ -0,0 +1,32 @@
+export interface FooterLink {
+  id: string;
+  label: string;
+  to: string;
+  order: number;
+}
+
+const links = ref<FooterLink[]>([]);
+
+function compareByOrder(a: FooterLink, b: FooterLink): number {
+  return a.order - b.order;
+}
+
+export function registerFooterLink(link: FooterLink): void {
+  const existingIndex = links.value.findIndex((entry) => entry.id === link.id);
+
+  if (existingIndex === -1) {
+    links.value = [...links.value, link];
+    return;
+  }
+
+  const next = [...links.value];
+  next[existingIndex] = link;
+  links.value = next;
+}
+
+export function useFooterLinks() {
+  const sortedLinks = computed<FooterLink[]>(() =>
+    [...links.value].sort(compareByOrder),
+  );
+  return { links: sortedLinks };
+}

package/frontend-vue/layers/dms-layout/app/composables/useHeaderActions.ts

@@ -0,0 +1,72 @@
+export interface HeaderAction {
+  id: string;
+  icon: string;
+  label: string;
+  onSelect: () => void;
+  order?: number;
+  isVisible?: () => boolean;
+  /** Renders the button as engaged — a toggle that is currently on. */
+  isActive?: () => boolean;
+}
+
+/**
+ * The action id the builder module registers. Core renders it on the existing
+ * builder button rather than as one more icon, and falls back to the
+ * "coming soon" popover when no module claims it.
+ */
+export const BUILDER_ACTION_ID = "dms-builder-edit";
+
+// Shared via keyed DMS app state (not a module-level ref) so any frontend module
+// can register an action without a build-time dependency on this layer: it just
+// pushes to useDmsState(HEADER_ACTIONS_STATE_KEY).
+//
+// Because actions carry callables (onSelect/isVisible), they must be registered
+// from CLIENT context (a `.client` plugin or component setup): function values
+// are not part of the SSR payload, so a server-side registration would arrive on
+// the client with its callbacks stripped. `registerHeaderAction` calls useDmsState,
+// so it must run inside the DMS app context. `useHeaderActions` defensively drops
+// any entry whose onSelect was lost, so a stray server-side registration
+// degrades to "button not shown" rather than a runtime crash.
+const HEADER_ACTIONS_STATE_KEY = "dms:header-actions";
+const DEFAULT_ORDER = 100;
+
+function actionOrder(action: HeaderAction): number {
+  return action.order ?? DEFAULT_ORDER;
+}
+
+function isActionRenderable(action: HeaderAction): boolean {
+  if (typeof action.onSelect !== "function") return false;
+  if (!action.isVisible) return true;
+  return action.isVisible();
+}
+
+function useHeaderActionState() {
+  return useDmsState<HeaderAction[]>(HEADER_ACTIONS_STATE_KEY, () => []);
+}
+
+export function registerHeaderAction(action: HeaderAction): void {
+  const actions = useHeaderActionState();
+  const existingIndex = actions.value.findIndex(
+    (entry) => entry.id === action.id,
+  );
+
+  if (existingIndex === -1) {
+    actions.value = [...actions.value, action];
+    return;
+  }
+
+  const next = [...actions.value];
+  next[existingIndex] = action;
+  actions.value = next;
+}
+
+export function useHeaderActions() {
+  const actions = useHeaderActionState();
+  const visibleActions = computed<HeaderAction[]>(() =>
+    actions.value
+      .filter(isActionRenderable)
+      .sort((a, b) => actionOrder(a) - actionOrder(b)),
+  );
+
+  return { actions: visibleActions };
+}