# LoomWeaver

> LoomWeaver: open-source plugin platform for Angular workbenches. Weavers (plugins) consume one uniform `ctx` contract from `@loomweaver/plugin-sdk` under a **default-deny** capability broker, and a thin **distribution** composes them with `@loomweaver/shell` into a product. The platform itself contains **zero domain logic** and ships **no server**; the backend seam is the product's own. Status: the platform is **built and published** as seven versioned npm packages, listed under *Packages* below. It is maintained by one person, its API still moves on patch releases before 1.0, and the demo application is its reference consumer.

This is a curated map for people, and their AI assistants, building on or integrating LoomWeaver. For a single-fetch brief with the complete contract inlined, see [`llms-full.txt`](https://loomweaver.dev/llms-full.txt). Read from the repository, the links are repo-relative; served from loomweaver.dev, they are absolute.

## Start here

- [Glossary](https://loomweaver.dev/glossary/): the words the docs use, one line each; platform, shell, host and workbench name the same thing.
- [Getting started](https://loomweaver.dev/getting-started/): a running, branded product with a plugin already contributing to it, in one command: `npx @loomweaver/cli init` inside an Angular application or an Nx workspace. The page then explains each step it ran. Start here.
- [Building with an AI assistant](https://loomweaver.dev/building-with-an-assistant/): the same path with an assistant doing the typing from the first weaver on: registering `@loomweaver/mcp` per tool (Claude Code, Cursor, VS Code), the prompts that reach its tools, and one run recorded as it happened.
- [The workbench your users get](https://loomweaver.dev/the-workbench/): what a product ships before its first plugin, one picture each from the live demo: panes and tabs, the palette and quick open, workspaces, the curation dialogs, context menus, settings and permissions, the plugin store with its consent prompt, and the shell's own keyboard shortcuts.
- [Architecture](https://loomweaver.dev/architecture/): the mental model, platform / weaver / distribution, the uniform `ctx`, default-deny capabilities, the two RPC boundaries. Read it once the tutorial has run.
- [Manual setup](https://loomweaver.dev/manual-setup/): the same app wired by hand (~15 min), without the scaffold's service worker and content-security policy; the shell renders inside the generated `app-root`, so nothing of `ng new`/Nx is deleted. Read it for the Nx differences, SSR (`RenderMode.Client`) and why Module Federation is not the plugin transport.
- [Samples](https://loomweaver.dev/samples/): complete copyable recipes, each compiling against the published contract: sidebar view with `VIEW_STATE`, routable surface, one command behind several triggers, settings, access gating, dialogs. It opens by naming which recipes the generator already writes, so scaffold those and type only the rest.

## Build

- [Authoring a weaver](https://loomweaver.dev/authoring-a-weaver/): the shape of a weaver (manifest, `activate(ctx)`, where snippets go) and the map of the how-to pages, one task each:
  - [Surfaces in a sidebar](https://loomweaver.dev/weaver/sidebar-surfaces/): a docked surface, and the custom-element escape hatch.
  - [A navigation tree in the sidebar](https://loomweaver.dev/weaver/navigation-tree/): `<lw-nav-tree>` declared as data; `lw-nav-select` handed to `ctx.navigateContent`, `current` from `ctx.activeContent`, folds kept for the session under `key`, the panel retitled with `ctx.retitleSurface`.
  - [View state that survives](https://loomweaver.dev/weaver/view-state/): `VIEW_STATE`: filter, sub-tab, scroll position in one shape; a write still held is sent when the page is left, which the built-in local store keeps and a server-backed store has to complete itself.
  - [Unsaved changes](https://loomweaver.dev/weaver/unsaved-changes/): `DirtySurface` and the Save, Discard, Cancel question.
  - [Your plugin's own store](https://loomweaver.dev/weaver/plugin-state/): `ctx.state`, one store shared by every surface of your plugin, kept per person wherever the product supplies an identity (never clear it on sign-out); a write still held is sent when the page is left, which the built-in local store keeps and a server-backed store has to complete itself.
  - [Containers](https://loomweaver.dev/weaver/containers/): a workspace in a tab, the arrangement it opens with, a child that stands for one item through `segment` and `CONTAINER_HANDLE`, leaving a child out with `ctx.setChildShown`.
  - [The content area](https://loomweaver.dev/weaver/content-area/): routable surfaces, tabs per pane, chromeless, closable (which refuses closing and nothing else), preview and pinned tabs, a tab `badge`, a surface's own `actions` in the pane header, panes and tab groups.
  - [Sub-routes and follows](https://loomweaver.dev/weaver/sub-routes-and-follows/): `subRoutes`, the rest of the address, tabs that follow the selection, `activeContent`.
  - [Menus](https://loomweaver.dev/weaver/menus/): `registerMenuItem`, a menu on a rail item, a bar item or a surface's action, opened by right-click or by activation (`menuTrigger`), a slot one plugin owns and others fill, `ctx.ui.openMenu`.
  - [Sandboxed surfaces](https://loomweaver.dev/weaver/sandboxed-surfaces/): `component` or `iframe`, the sandbox bootstrap, the frame UI kit.
  - [Commands and their triggers](https://loomweaver.dev/weaver/commands/): one behaviour behind shortcut, bar and rail items, palette and menu.
  - [Access gating](https://loomweaver.dev/weaver/access-gating/): `access` on contributions and `ctx.session`.
  - [Icons and theme](https://loomweaver.dev/weaver/icons-and-theme/): `ctx.contributeIcons`, `ctx.contributeTheme`.
  - [Host UI and host facts](https://loomweaver.dev/weaver/host-ui-and-facts/): `ctx.ui` dialogs and toasts, `ctx.host`.
  - [Settings sections](https://loomweaver.dev/weaver/settings/)
  - [Translations](https://loomweaver.dev/weaver/i18n/)
- [Building a distribution](https://loomweaver.dev/building-a-distribution/): the composition root (`app.config.ts`), which door a decision goes through, the composition report (`loomweaver.report()`), and the map of the how-to pages, one decision each:
  - [Layout](https://loomweaver.dev/distribution/layout/): regions and docks.
  - [Content-area routing](https://loomweaver.dev/distribution/content-routing/): `provideShellRouter`, following tabs.
  - [Workspaces](https://loomweaver.dev/distribution/workspaces/): `provideWorkspaces`, an unusable workspace, telling saved ones apart.
  - [Resetting the arrangement](https://loomweaver.dev/distribution/resetting/): the reset control and what it asks.
  - [Switching capabilities off](https://loomweaver.dev/distribution/switching-capabilities-off/): `provideShellFeatures`, the switch takes the gesture and the affordance; `splitRightButton`/`splitDownButton` take the pane toolbar's split button alone, for a product that offers splitting by dragging to a pane's edge.
  - [Surface retention](https://loomweaver.dev/distribution/surface-retention/): the product-wide default.
  - [Branding](https://loomweaver.dev/distribution/branding/)
  - [Bringing your own CSS framework](https://loomweaver.dev/distribution/css-frameworks/): the pre-compiled stylesheet instead of Tailwind, your framework in a cascade layer, `theme --preset bootstrap` for the token mapping. Read it before importing Bootstrap next to the shell.
  - [Capabilities](https://loomweaver.dev/distribution/capabilities/): grants, default-deny, `provideRequiredPlugins`.
  - [Auth integration](https://loomweaver.dev/distribution/auth/): `provideAuthSource`, your login UI, `provideUnauthorizedRedirect`.
  - [Persistence stores](https://loomweaver.dev/distribution/persistence/): two ports of one shape, the storage-key inventory, identity-scoped stores.
  - [Windows and sync](https://loomweaver.dev/distribution/windows-and-sync/): cross-tab live sync, pop-out windows.
  - [Frame plugins](https://loomweaver.dev/distribution/frame-plugins/): `provideFramePlugins`, `@loomweaver/frame-kit`.
  - [Plugin store](https://loomweaver.dev/distribution/plugin-store/): `providePluginCatalog`, runtime install, updates.
  - [Icons, translations and rewording](https://loomweaver.dev/distribution/icons-and-i18n/): `provideIcons`, namespaces, `provideTranslationOverrides`.
  - [Recomposing host chrome](https://loomweaver.dev/distribution/recomposing-chrome/): palette and quick-open entries, curating settings, dropping a route.
  - [PWA and delivery](https://loomweaver.dev/distribution/pwa/)
- [Driving your product with an AG-UI agent](https://loomweaver.dev/ag-ui-agents/): the path from `weaver --id <id> --agent` to a product an AG-UI agent drives, including which calls get a confirmation (a command declares `agentConsent`, your `before` hook acts on it, and a decision can only narrow). Read it before [agent tools](https://loomweaver.dev/reference/agent-tools/), which is the adapter function by function.
- [The plugin system](https://loomweaver.dev/plugins/): the distribution's view of plugins: three rungs (trusted composed, sandboxed iframe over RPC, community-installed at runtime) against one contract, which parts of `ctx` cross the sandbox, default-deny capabilities, the lifecycle. Read it before deciding how a plugin arrives or what a user may revoke, disable or uninstall.
- [Backend integration](https://loomweaver.dev/backend-integration/): the product hand-off; the platform ships no server and has three ports (settings store, working-state store, auth source) plus a translation loader, which is a provider, not a port. Read it when wiring a real backend behind the local, anonymous defaults.

## Concepts

Why the workbench behaves as it does; short, each linking to the how-to pages that act on it.

- [Surfaces and panes](https://loomweaver.dev/concepts/surfaces-and-panes/): one contract for everything shown; a pane is a tab group.
- [The address](https://loomweaver.dev/concepts/the-address/): one pane carries it; what has none.
- [Retention and unsaved work](https://loomweaver.dev/concepts/retention-and-unsaved-work/): destroyed when clean; the question is asked by the action.
- [Capabilities and trust](https://loomweaver.dev/concepts/capabilities-and-trust/): default-deny, three rungs, access is not a capability.
- [Workspaces](https://loomweaver.dev/concepts/workspaces/): a whole way of working, its baseline, two origins.

## The contract: public API

- [`@loomweaver/plugin-sdk` public API](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/index.ts): everything a plugin imports (nothing else is public API).
- [Plugin contract](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/lib/plugin/plugin.ts): `Plugin` and `PluginManifest`. The `ctx` a plugin holds is [`PluginContext`](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/lib/plugin/plugin-context.ts); its [host services](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/lib/host-ui/host-services.ts) are `PluginUi` (`ctx.ui`), `PluginHost` (`ctx.host`) and `PluginSession` (`ctx.session`).
- [Capabilities](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/lib/plugin/capability.ts): the coarse capabilities a plugin *declares* and a distribution *grants*, default-deny (`contributions`/`ui`/`host`/`navigation`/`session`/`theme`/`automation`).
- [Access gating](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/plugin-sdk/src/lib/plugin/auth.ts): `AuthSnapshot`, `AccessRequirement`, and the pure predicates: how a contribution reacts to login state + roles. Distinct from capabilities: what a *user* may see vs. what a *plugin* may do.
- [Worked example: the testbed weaver](https://github.com/yesbert/loomweaver/blob/main/platform/libs/weavers/testbed-weaver/src/lib/testbed.plugin.ts): a real in-repo plugin (dogfood). All domain content lives in a weaver like this, never in the core.
- [`loom-testbed` composition root](https://github.com/yesbert/loomweaver/blob/main/platform/apps/loom-testbed/src/main.ts): a worked distribution, read as a table of contents: shell, branding and session in `main.ts`, the layout, workspaces, plugins with their grants, cross-tab sync and capture wiring in named files under `app/`.

## Scaffolding & tooling (AI-assisted setup)

Deterministic scaffolding + validation for building on LoomWeaver. Prefer these over hand-wiring.

- [Scaffolding](https://loomweaver.dev/scaffolding/): the guide: which of the three adapters applies to you, what the tools return, and every weaver option.
- [`@loomweaver/devkit`](https://github.com/yesbert/loomweaver/blob/main/platform/libs/tooling/devkit/README.md): the **Nx generator collection** (`npm i -D @loomweaver/devkit`), the fullest adapter, since Nx lets it also register the project and add the tsconfig alias. Read it for the generators (`weaver`, `frame-plugin`, `distribution`, `auth-source`, `settings-store`, `theme`, `layout`), their flags and the pure cores `generate(recipe, input)` and `validate*`.
- [`@loomweaver/cli`](https://github.com/yesbert/loomweaver/blob/main/platform/libs/tooling/cli/README.md): the scaffolding **CLI**, the primary path for a product repo because it needs no Nx workspace, no checkout and no assistant. `init` takes an existing Angular application or Nx workspace to a running product in one command (installs with the lockfile's package manager, scaffolds the distribution and a first weaver, idempotent, `--dry-run`). Read it for `--dry-run`/`--force`/`--strict` and the validators `validate-manifest`, `validate-i18n`, `validate-catalog`, `validate-commands`.
- [`@loomweaver/mcp`](https://github.com/yesbert/loomweaver/blob/main/platform/libs/tooling/mcp/README.md): an MCP server exposing the same scaffolding + validation as tools (`scaffold_*` return a file map; `validate_*` return findings) for AI assistants. Register it in `.mcp.json` with `{ "command": "npx", "args": ["-y", "@loomweaver/mcp"] }`.

## Distribution API

- [Distribution API](https://loomweaver.dev/distribution-api/): every runtime service a distribution may inject (dialogs, notifications, settings, commands, session, tabs, panes, workspaces, reset, sidebars, feature switches, plugin store, updates, pop-outs, sync) plus contributing chrome without a plugin. Read it when your product's own code must do what a user does by hand; a plugin never injects these, it goes through the brokered `ctx`.
  - [Composition](https://loomweaver.dev/distribution-api/composition/): the provider surface, `provideShell` options, `ContributionRegistry` and its signals, ids that replace and ids that omit.
  - [Switches](https://loomweaver.dev/distribution-api/switches/): `FeatureSwitches`, reading and changing what `provideShellFeatures` declared while the app runs.
  - [Tabs](https://loomweaver.dev/distribution-api/tabs/): `ContentTabsService`, open, close, pin, preview and reveal a tab from your own code.
  - [Panes](https://loomweaver.dev/distribution-api/panes/): `PaneService` and `PaneHandle`, split, maximise, minimise, move a tab, the facts per pane.
  - [Workspaces](https://loomweaver.dev/distribution-api/workspaces/): `WorkspaceService`, switch, save, reset, remove, and the claims a path settles by.
  - [Sidebars](https://loomweaver.dev/distribution-api/sidebars/): `SidebarService`, collapse, expand, width, hide and show a view.
  - [Reset](https://loomweaver.dev/distribution-api/reset/): `AppResetService`, the one question, with or without the workspaces.
  - [Dialogs and toasts](https://loomweaver.dev/distribution-api/dialogs-and-toasts/): `DialogService` and `NotificationService`, the same seam `ctx.ui` uses, `DialogInstance` for an outlet of your own.
  - [Settings](https://loomweaver.dev/distribution-api/settings/): `SettingsService`, register, omit and open a section.
  - [Commands](https://loomweaver.dev/distribution-api/commands/): `CommandService`, execute, run, availability, the chord for display, `Triggerable`, and the `CommandInvoker` seam.
  - [Session](https://loomweaver.dev/distribution-api/session/): `AuthContext`, the snapshot and the predicates the chrome gates on.
  - [Appearance](https://loomweaver.dev/distribution-api/appearance/): `ThemeService` and `FontScaleService`, the mode and the text size.
  - [Plugins at runtime](https://loomweaver.dev/distribution-api/plugins-at-runtime/): `PluginEnablementService`, `CapabilityGrantService`, `PluginInstallService`, on, off, grants and installs from your own code.
  - [Windows and sync](https://loomweaver.dev/distribution-api/windows-and-sync/): `PopoutService`, `StateSyncService`, `UpdateService` and `VersionService`.
  - [A picture of the workbench](https://loomweaver.dev/distribution-api/capture/): `WorkbenchCaptureService`, a drawing of what the user is seeing with no browser permission prompt and plugin surfaces on it, for a fault report the user writes without leaving the application.

## Platform reference

- [Shell anatomy](https://loomweaver.dev/reference/shell-anatomy/): the region vocabulary (rail / panel / bar / content) and docks a distribution declares.
- [Callable commands](https://loomweaver.dev/reference/callable-commands/): opening a command to a caller that is not the user: described `arguments`, `answers`, `description`, `callable`, `agentConsent`, `ctx.invokeCommand`, `ctx.invocableCommands()`. Read it before another plugin or an agent should call your command; reaching another plugin's command needs `automation`.
- [Agent tools](https://loomweaver.dev/reference/agent-tools/): `@loomweaver/ag-ui`, the headless adapter that offers the workbench's own commands to an AG-UI agent as tools: `commandTools(ctx)`, `list()`, `receive(event)`, the `before` hook and the `agentConsent` it decides from. Read it after the AG-UI guide, function by function.
- [Access gating](https://loomweaver.dev/reference/access-gating/): the complete `access` reference: the `AuthSnapshot`/`AccessRequirement` vocabulary, `hide`/`disable`, gated routes, the three readers of the session, `onIdentityChange`. Read it for why capability grants and access gating are orthogonal.
- [Routing](https://loomweaver.dev/reference/routing/): the content area **is** the Angular router: `provideShellRouter()` wraps `provideRouter()`, `routable` surfaces become ordinary routes, and `routerLink`/`router.navigate`/`ActivatedRoute` behave normally. Read it for what you do not write (`Routes`, `canActivate`), how every navigation reaches an existing pane, and the two off-router cases.
- [Design tokens & `<lw-*>` vocabulary](https://loomweaver.dev/reference/design-tokens/): the semantic tokens and host UI building blocks for plugin templates (never raw palette colors); colour and type only, no size tokens by decision. Read it before writing a template or overriding a dimension with plain unlayered CSS.
- [Icons](https://loomweaver.dev/reference/icons/): every icon name `<lw-icon>` resolves out of the box, semantic names, generated from the shell's icon map. Read it before naming an icon or adding your own with `ctx.contributeIcons` or `provideIcons`.
- [Accessibility](https://loomweaver.dev/reference/accessibility/): the WCAG 2.1 AA guardrail the host meets and weavers inherit.
- [Operations](https://loomweaver.dev/reference/operations/): for whoever runs or contributes to the repository: what bites, what it costs, and the guards the repository runs.
- [Documentation map](https://loomweaver.dev/overview/): the documentation's own index, guides by task and reference by subject.
- [`@loomweaver/shell`: the neutral host chrome](https://github.com/yesbert/loomweaver/blob/main/platform/libs/core/shell/README.md): renders regions and holds contributions; domain-pure.

## Packages

Seven npm packages, one shared version: `@loomweaver/plugin-sdk`, `@loomweaver/shell`, `@loomweaver/mcp` (the AI-scaffolding MCP server), `@loomweaver/cli` (the scaffolding CLI, same generators driven by flags), `@loomweaver/devkit` (the Nx generator collection), `@loomweaver/frame-kit` (static UI assets a distribution serves under `/frame-kit/` for sandboxed plugins), `@loomweaver/ag-ui` (the AG-UI adapter, headless). No server packages: the platform is frontend-only.

## Releases

- [Changelog](https://loomweaver.dev/changelog/): every release, newest first, generated from the pull requests each one merged; the same list as [GitHub releases](https://github.com/yesbert/loomweaver/releases). Packages move on patch releases before 1.0.

## Examples

- [Assistant workbench](https://github.com/yesbert/loomweaver/tree/main/examples/assistant-workbench): a support inbox built on the published packages that an AI assistant operates through the product's own callable commands over AG-UI, with a real model through OpenRouter and the reader's own key. `npm install && npm start`, then ask it for something.

## For AI assistants

- [`llms-full.txt`](https://loomweaver.dev/llms-full.txt): the complete contract (interfaces + provider signatures) and canonical distribution/weaver code, inlined for single-fetch ingestion.
- [Agent skill](https://loomweaver.dev/skills/loomweaver/SKILL.md): the order of work as a `SKILL.md`, for tools that read the format (Claude Code, Cursor, VS Code with Copilot). Optional; it states procedure and links the pages, and repeats no part of the contract.
- [Brand assets](https://github.com/yesbert/loomweaver/blob/main/assets/brand/): logo and colors (blue `#2E96C9`, gold `#C59A2F`).