@ydtb/tk-scope

Scope toolkit for Anvil — tools, scopes, surface definitions, and deployment helpers.

Four entry points:

• ./core — universal (no React). defineTool, defineScope, hierarchy utilities.
• ./client — React-requiring. createAnvilApp, scope hooks, portals, Viewing Scope.
• ./server — server-only. createToolServer, surface processors.
• ./cloudflare — Cloudflare Workers wrapper.

Viewing Scope — useViewingScope + ViewingScopeProvider

At a parent scope (e.g., company), users can "peek" at a single descendant (e.g., one location) without navigating away. The selection is mirrored into the URL as ?view=<descendantScopeId> so refresh and bookmarks preserve it.

Wrap the page tree with ViewingScopeProvider, pass the parent scope + the list of descendants with the current tool installed. Read selection state via useViewingScope().

import { ViewingScopeProvider, useViewingScope } from "@ydtb/tk-scope/client"

function CompanyPage() {
  return (
    <ViewingScopeProvider
      parentScope="company"
      parentScopeId="co_123"
      availableDescendants={[
        { scope: "location", scopeId: "loc_a", label: "Austin" },
        { scope: "location", scopeId: "loc_b", label: "Boston" },
      ]}
    >
      <Dashboard />
    </ViewingScopeProvider>
  )
}

function Dashboard() {
  const { viewingScope, getEffectiveScope } = useViewingScope()
  const { scope, scopeId } = getEffectiveScope()
  // Fetch data for (scope, scopeId). Aggregate → parent; Specific → descendant.
}

• ?view= query param is read on mount, written via history.replaceState on setViewingScope, and resynced from popstate (back/forward).
• Invalid ?view= values (stale bookmarks, typos) fall back to aggregate and emit a console.warn — never crash the UI.
• Leaf scopes get hasDescendants === false; consumers hide the selector.

For the dropdown UI, see @ydtb/tk-scope-ui/components/scope-view-selector.