@cratis/scene.components 0.1.0

package/.storybook/main.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { StorybookConfig } from "@storybook/react-vite";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import type { InlineConfig } from 'vite';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const config: StorybookConfig = {
+    // Scoped away from `dist/` so a story is never indexed twice - once as source and once as the
+    // tsc-emitted copy beside it.
+    stories: ["../*.stories.@(js|jsx|mjs|ts|tsx)", "../!(dist|node_modules)/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+    addons: [getAbsolutePath("@storybook/addon-links")],
+    framework: { name: getAbsolutePath("@storybook/react-vite"), options: {} },
+    async viteFinal(config: InlineConfig) {
+        config.resolve = config.resolve || {};
+        config.resolve.alias = {
+            ...config.resolve.alias,
+            '@cratis/scene.engine': resolve(__dirname, '../../engine/index.ts'),
+            '@cratis/scene.model': resolve(__dirname, '../../model/index.ts'),
+            '@cratis/scene.react': resolve(__dirname, '../../react/index.ts'),
+        };
+
+        // `@cratis/arc`, `@cratis/arc.react` and `@cratis/fundamentals` are peer dependencies of
+        // `@cratis/components` that the *host application* supplies. A Storybook preview is not a host:
+        // it has no Arc client and no backend, which is exactly the situation this package is designed
+        // around, so they are not installed here.
+        //
+        // Every adapter that reaches them does so through a dynamic `import()`, which puts the Arc-bound
+        // half of the library in its own chunk. Marking these external lets that chunk be emitted with
+        // its imports left bare, instead of failing the build; no story loads the chunk, because no
+        // story registers a binding. If one ever did, the chunk would fail to load in the browser and
+        // the `ArcRuntimeBoundary` around it would show that - which is the same thing a real host
+        // without Arc installed would see, and is worth seeing rather than hiding.
+        config.build = config.build || {};
+        config.build.rollupOptions = {
+            ...(config.build.rollupOptions ?? {}),
+            external: [/^@cratis\/arc/, '@cratis/fundamentals'],
+        };
+        // Vite 8 minifies CSS with lightningcss, which rejects the whole bundle over one invalid file:
+        // `@cratis/components@2.9.0` ships `dist/esm/TimeMachine/Properties.css` with `//` line comments,
+        // which are not CSS. esbuild's minifier tolerates them. This is an upstream defect and the
+        // workaround belongs here, in preview tooling, rather than anywhere it could hide the problem -
+        // remove this line once the Components package ships that file with `/* */` comments.
+        config.build.cssMinify = 'esbuild';
+        return config;
+    },
+};
+export default config;
+
+function getAbsolutePath(value: string): string {
+    return dirname(fileURLToPath(import.meta.resolve(join(value, "package.json"))));
+}

package/.storybook/preview.tsx

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Preview } from '@storybook/react';
+import { CratisComponentsProvider } from '@cratis/components/Common';
+
+// The three layers a `@cratis/components` component needs to look like itself, in the order they
+// resolve. PrimeReact 10 ships every widget's *structural* CSS inside the theme file - there is no
+// separate primitives stylesheet - so without a theme the wrapped widgets render as bare HTML. The
+// library's own sheet adds its Tailwind utilities and the `--cratis-*` token layer on top, and this
+// package's bridge puts Scene's `--scene-*` tokens in front of that wherever a Scene theme is applied.
+import 'primereact/resources/themes/lara-light-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+import '../theme/sceneTokenBridge.css';
+
+/**
+ * Every story renders inside `CratisComponentsProvider`, the library's own configuration provider over
+ * PrimeReact's. Without it the wrapped components fall back to PrimeReact's defaults rather than
+ * Cratis', so a story would be showing something subtly different from what an application renders -
+ * which defeats the point of having stories at all.
+ */
+const preview: Preview = {
+    decorators: [
+        Story => (
+            <CratisComponentsProvider>
+                <Story />
+            </CratisComponentsProvider>
+        ),
+    ],
+    parameters: {
+        controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
+    },
+};
+
+export default preview;

package/CratisComponents.stories.tsx

@@ -0,0 +1,235 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, fireEvent, within } from 'storybook/test';
+import { ExternalComponent, HorizontalAlignment, Theme, VerticalAlignment, Visibility } from '@cratis/scene.model';
+import { SceneElementView, SceneThemeProvider } from '@cratis/scene.react';
+import { cratisComponents } from './cratisComponents';
+
+/**
+ * Builds the `ExternalComponent` a screen compiles to, with the inherited layout properties at their
+ * neutral values. Stories are about `properties` and `slots`; everything else is noise, so it lives here.
+ */
+function component(id: string, componentName: string, properties: Record<string, unknown> = {}, slots: Record<string, ExternalComponent[]> = {}): ExternalComponent {
+    return {
+        id,
+        name: id,
+        componentName,
+        properties,
+        slots,
+        visibility: Visibility.Visible,
+        isEnabled: true,
+        opacity: 1,
+        size: {},
+        zIndex: 0,
+        minimumSize: {},
+        maximumSize: {},
+        margin: { left: 0, top: 0, right: 0, bottom: 0 },
+        horizontalAlignment: HorizontalAlignment.Stretch,
+        verticalAlignment: VerticalAlignment.Stretch,
+    };
+}
+
+const toolbar = component('toolbar', 'Cratis.Components:toolbar', { orientation: 'horizontal' }, {
+    content: [
+        component('new', 'Cratis.Components:toolbarButton', { icon: 'pi pi-plus', title: 'New invoice' }),
+        component('refresh', 'Cratis.Components:toolbarButton', { icon: 'pi pi-refresh', title: 'Refresh' }),
+        component('separator', 'Cratis.Components:toolbarSeparator', { orientation: 'horizontal' }),
+        component('group', 'Cratis.Components:toolbarGroup', { orientation: 'horizontal' }, {
+            content: [
+                component('approve', 'Cratis.Components:toolbarButton', { icon: 'pi pi-check', title: 'Approve', active: true }),
+                component('reject', 'Cratis.Components:toolbarButton', { icon: 'pi pi-times', title: 'Reject' }),
+            ],
+        }),
+    ],
+});
+
+const statusDropdown = component('status', 'Cratis.Components:dropdown', {
+    placeholder: 'Any status',
+    showClear: true,
+    options: [
+        { label: 'Draft', value: 'draft' },
+        { label: 'Approved', value: 'approved' },
+        { label: 'Paid', value: 'paid' },
+    ],
+});
+
+const invoicesTable = component('invoices', 'Cratis.Components:dataTable', {
+    query: 'AllInvoices',
+    emptyMessage: 'No invoices yet',
+    dataKey: 'invoiceId',
+});
+
+const invoicesScreen = component('page', 'Cratis.Components:page', { title: 'Invoices', showTitle: true, panel: true }, {
+    content: [toolbar, statusDropdown, invoicesTable],
+});
+
+const meta = {
+    title: 'Packages/Cratis Components',
+    component: SceneElementView,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component:
+                    'The `Cratis.Components` Scene package: `@cratis/components` exposed as resolvable Scene components. ' +
+                    'Every story renders a real `ExternalComponent` tree through the real `SceneElementView` and the real ' +
+                    'component registry, so what is shown is exactly what a `.play` screen resolves to.',
+            },
+        },
+    },
+    args: {
+        registry: cratisComponents,
+        resolveBinding: () => undefined,
+    },
+} satisfies Meta<typeof SceneElementView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** An invoices screen: page chrome, a toolbar, a filter dropdown, and a table waiting on its query. */
+export const Playground: Story = {
+    args: { element: invoicesScreen },
+};
+
+/**
+ * What design-time preview normally looks like. Nothing is registered in the binding registry, so every
+ * Arc-bound component names the binding it wanted instead of rendering blank or throwing - and the rest
+ * of the screen is entirely usable while that is true.
+ */
+export const MissingBindings: Story = {
+    args: {
+        element: component('unbound', 'Cratis.Components:page', { title: 'Unbound', showTitle: true }, {
+            content: [
+                component('table', 'Cratis.Components:dataTable', { query: 'AllInvoices', emptyMessage: 'None' }),
+                component('live', 'Cratis.Components:observableDataTable', { query: 'InvoicesInFlight', emptyMessage: 'None' }),
+                component('form', 'Cratis.Components:commandForm', { command: 'RegisterInvoice' }),
+                component('nameless', 'Cratis.Components:dataPage', { title: 'No query named' }),
+                component('field', 'Cratis.Components:inputTextField', { title: 'No property named' }),
+            ],
+        }),
+    },
+};
+
+/** The toolbar family - buttons, a group and a separator - inside its own container. */
+export const Toolbar: Story = {
+    args: {
+        element: component('page', 'Cratis.Components:page', { title: 'Toolbar', showTitle: true }, { content: [toolbar] }),
+    },
+};
+
+/** The editors: a schema editor, a breadcrumb trail and a document editor, all Arc-free. */
+export const Editors: Story = {
+    args: {
+        element: component('page', 'Cratis.Components:page', { title: 'Editors', showTitle: true }, {
+            content: [
+                component('trail', 'Cratis.Components:objectNavigationalBar', { navigationPath: ['shipping', 'address'] }),
+                component('schema', 'Cratis.Components:schemaEditor', {
+                    eventTypeName: 'InvoiceRegistered',
+                    canEdit: true,
+                    schema: {
+                        title: 'InvoiceRegistered',
+                        type: 'object',
+                        properties: {
+                            number: { type: 'string' },
+                            amount: { type: 'number' },
+                            issued: { type: 'string', format: 'date-time' },
+                        },
+                    },
+                }),
+                component('document', 'Cratis.Components:objectContentEditor', {
+                    editMode: true,
+                    object: { number: 'INV-1001', amount: 4200 },
+                    schema: { type: 'object', properties: { number: { type: 'string' }, amount: { type: 'number' } } },
+                }),
+            ],
+        }),
+    },
+};
+
+/** The tooltip, icon and error boundary wrappers, in a small composition. */
+export const InContext: Story = {
+    args: {
+        element: component('page', 'Cratis.Components:page', { title: 'Invoice INV-1001', showTitle: true, panel: true }, {
+            content: [
+                component('guard', 'Cratis.Components:errorBoundary', {}, {
+                    content: [
+                        component('hint', 'Cratis.Components:tooltip', { content: 'Approved on 5 January', position: 'right' }, {
+                            content: [component('icon', 'Cratis.Components:icon', { icon: 'pi pi-check-circle' })],
+                        }),
+                        component('filters', 'Cratis.Components:filterPanel', {
+                            label: 'Filters',
+                            filters: [
+                                {
+                                    key: 'status',
+                                    label: 'Status',
+                                    multi: true,
+                                    options: [
+                                        { key: 'draft', label: 'Draft', count: 12 },
+                                        { key: 'approved', label: 'Approved', count: 44 },
+                                    ],
+                                },
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        }),
+    },
+};
+
+/**
+ * A Scene theme driving `@cratis/components` through the token bridge.
+ *
+ * Neither side knows about the other: the theme carries semantic Scene tokens, `SceneThemeProvider`
+ * writes them as `--scene-*` custom properties, and this package's stylesheet maps those onto the
+ * `--cratis-*` names the library reads. Nothing in `@cratis/components` was changed to make this work.
+ */
+const midnight: Theme = {
+    name: 'Midnight',
+    compatibleWith: ['Cratis.Components', 'PrimeReact', 'Tailwind'],
+    isDark: true,
+    description: 'A dark Scene theme, applied to Cratis Components entirely through design tokens.',
+    tokens: {
+        'primary.color': '#a78bfa',
+        'primary.contrastColor': '#1e1b4b',
+        'surface.background': '#0f172a',
+        'surface.card': '#1e293b',
+        'surface.border': '#334155',
+        'surface.hover': '#273449',
+        'surface.overlay': '#1e293b',
+        'text.color': '#e2e8f0',
+        'text.mutedColor': '#94a3b8',
+        'highlight.background': '#312e81',
+        'highlight.color': '#e0e7ff',
+        'content.borderRadius': '10px',
+        'focus.ring': '0 0 0 0.2rem #4c1d95',
+    },
+};
+
+export const Themed: Story = {
+    args: { element: invoicesScreen },
+    render: args => (
+        <SceneThemeProvider theme={midnight}>
+            <SceneElementView {...args} />
+        </SceneThemeProvider>
+    ),
+};
+
+/**
+ * The breadcrumb trail is stateful: clicking a crumb truncates the path, which the underlying component
+ * reports and the adapter applies.
+ */
+export const Interactive: Story = {
+    args: {
+        element: component('trail', 'Cratis.Components:objectNavigationalBar', { navigationPath: ['shipping', 'address', 'street'] }),
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        fireEvent.click(canvas.getByText('address'));
+        await expect(canvas.queryByText('street')).toBeNull();
+    },
+};

package/README.md

@@ -0,0 +1,192 @@
+# @cratis/scene.components
+
+The Scene package that exposes [`@cratis/components`](https://www.npmjs.com/package/@cratis/components) — the
+Cratis React component library — as resolvable Scene components.
+
+User-facing documentation lives in [`Documentation/components-package/`](../../../Documentation/components-package/index.md).
+This file is the contributor's note: how the package is laid out, and why the load-bearing decisions were
+made the way they were.
+
+## The constraint everything is shaped around
+
+Most of `@cratis/components` is **Arc-bound**. `DataPage`, `DataTableForQuery`,
+`DataTableForObservableQuery`, `AutoCommandForm`, `CommandDialog` and `StepperCommandDialog` all take a
+*query or command class constructor* and talk to a live backend through `@cratis/arc.react`.
+
+A Scene `ExternalComponent` carries a `properties` bag of plain values and named `slots`. There is no way to
+put a TypeScript class in one, and there should not be — a `.play` document is text, compiled by Stage and
+read back by Studio, and nothing in that round trip can carry a class.
+
+So an adapter cannot conjure a query class out of a property string. The only honest seam is that the thing
+in the screen *is a name*, and a name needs somewhere to become a class.
+
+### The binding registry
+
+`bindings/bindingRegistry.ts`:
+
+```typescript
+registerQuery(name: string, queryClass: BoundConstructor): void
+registerQueries(bindings: Record<string, BoundConstructor>): void
+resolveQuery(name: string): BoundConstructor | undefined
+
+registerCommand(name: string, commandClass: BoundConstructor): void
+registerCommands(bindings: Record<string, BoundConstructor>): void
+resolveCommand(name: string): BoundConstructor | undefined
+
+registeredQueryNames(): string[]
+registeredCommandNames(): string[]
+clearBindings(): void
+```
+
+A host — Stage's generated application, or Studio's preview when it is wired to a real backend — registers
+the real generated Arc proxies under the names screens refer to them by. Adapters look them up at render
+time through `resolveElementBinding`, which reads `properties.query` or `properties.command` depending on the
+`BindingKind`.
+
+Design notes:
+
+- **Queries and commands are separate namespaces.** They are opposite halves of CQRS and a screen means
+  exactly one at each site; letting one satisfy the other would turn a modeling mistake into a runtime one.
+- **`BoundConstructor` is `new (...args: never[]) => object`,** not an Arc type. Scene deliberately does not
+  depend on Arc. Whether a registered class really is a query is checkable where the host registers it, with
+  the real Arc types in scope — which is where that check belongs.
+- **Re-registering a name replaces it**, so a host can re-register on hot reload.
+- **`clearBindings()` exists** because module-level state is right for a host that registers once and wrong
+  for Studio switching projects, or for a spec that must not inherit the previous one's registrations.
+
+### A missing binding is a placeholder, never a throw
+
+`resolveQuery` returns `undefined`, and every Arc-bound adapter renders `MissingBinding`:
+
+```text
+Unresolved query binding 'AllInvoices' on Cratis.Components:dataTable
+Missing query binding on Cratis.Components:dataTable
+```
+
+Two messages, because they are two different mistakes — one needs the host to register the name, the other
+needs the screen edited. The presentation deliberately matches `UnresolvedComponent` in `@cratis/scene.react`.
+
+Studio's design-time preview usually has nothing registered at all and must still show a usable layout: one
+unbound table costs one dashed box, not the whole screen.
+
+### Arc is loaded lazily
+
+`@cratis/arc`, `@cratis/arc.react` and `@cratis/fundamentals` are peer dependencies of `@cratis/components`
+that the *host* supplies. They are not installed in this repository, and a design surface is not a host.
+
+Every adapter that reaches them does so through a dynamic `import()` inside `React.lazy`, wrapped in
+`ArcRuntimeBoundary` (`Suspense` + the library's own `ErrorBoundary`). A screen built only from the library's
+Arc-free half never pulls the Arc client in, and an unbound component never even reaches the import.
+
+This splits the library cleanly, and the split is the library's own:
+
+| Arc-free (static import) | Arc-bound (lazy import) |
+|---|---|
+| `Common`, `Dropdown`, `Filter`, `Toolbar`, `SchemaEditor`, `TimeMachine`, `ObjectContentEditor`, `ObjectNavigationalBar` | `DataPage`, `DataTables`, `CommandForm`, `CommandDialog`, `Dialogs` |
+
+The Storybook build externalizes the Arc packages (`.storybook/main.ts`) so the lazy chunk can be emitted
+with its imports left bare. No story loads that chunk, because no story registers a binding.
+
+## Naming and shadowing
+
+Bare names are `lowerCamelCase` and abstract — `dataTable`, not `DataTableForQuery` — registered under
+`componentRegistryKey('Cratis.Components', name)`.
+
+`table` and `dialog` deliberately reuse names `core` and `PrimeReact` declare. A profile listing
+`core`, `PrimeReact`, `Cratis.Components` in that order resolves both here and records the others as
+shadowed. Both replacements are better for a Cratis application: `DataTableForQuery` performs the query
+rather than being handed rows, and the Cratis `Dialog` resolves its result through Arc's dialog context.
+
+**`card` is deliberately not declared.** `@cratis/components` ships no card; the nearest thing is `Page`'s
+`panel` chrome, whose `.panel` class the consuming application defines. Shadowing `card` with that would make
+the name resolve to something worse — an override is only justified when the replacement is better for every
+screen that already writes the name.
+
+`dataTable` and `table` are the same adapter under two names, so adopting the package does not require
+rewriting screens.
+
+## Token bridge
+
+`theme/sceneTokenBridge.css`, exported as `@cratis/scene.components/styles`, maps Scene's `--scene-*` tokens
+onto the `--cratis-*` names `@cratis/components` reads:
+
+```css
+--cratis-surface-card: var(--scene-surface-card, var(--p-content-background, var(--surface-card)));
+/*                         ^ Scene theme           ^ PrimeReact v11         ^ v10 legacy */
+```
+
+It extends the library's own fallback chain rather than replacing it, so a partial theme leaves the rest as
+the PrimeReact theme had it. The rules are scoped to `[data-scene-theme-root], [data-scene-theme]` — never
+`:root`, where `--scene-*` does not exist and every mapping would resolve to nothing.
+
+The vocabulary is thirteen tokens, verified against `theme/themePresets.ts` in `@cratis/scene.primereact` so
+both packages write themes in one language: `primary.color`, `primary.contrastColor`, `surface.background`,
+`surface.card`, `surface.border`, `surface.hover`, `surface.overlay`, `text.color`, `text.mutedColor`,
+`highlight.background`, `highlight.color`, `content.borderRadius`, `focus.ring`.
+
+## Deliberately not covered
+
+- **`PivotViewer`** — drags in `pixi.js`, a full WebGL renderer, into every bundle that lists this package,
+  for a faceted browser that has nothing to show at design time. An application that wants it imports it
+  directly.
+- **`card`** — see above.
+- **`column`** — PrimeReact's `Column` is a configuration element and belongs to the PrimeReact package;
+  a duplicate here would be a shadow with nothing behind it. Columns come through the `content` slot.
+- **Event handlers** — Scene has no action-binding seam yet. Where a callback drives a component's own
+  visible state the adapter holds it (`useEditableCopy`), so the breadcrumb, schema editor and time machine
+  behave like themselves; where it would reach outside, the adapter exposes nothing rather than a handler
+  that quietly does nothing.
+- **`calendarField` date bounds** — would arrive as strings and have to be parsed here; a range that silently
+  misparses is worse than none. That rule belongs in the command's validator.
+
+## Layout
+
+```
+bindings/    the registry, BindingKind, BoundConstructor, MissingBinding, ArcRuntimeBoundary
+pages/       page, dataPage, formElement
+data/        dataTable, table, observableDataTable
+forms/       commandForm; forms/fields/ the twelve field types
+dialogs/     dialog, confirmationDialog, busyIndicatorDialog, commandDialog, stepperCommandDialog
+common/      icon, tooltip, dropdown, errorBoundary
+editors/     objectContentEditor, objectNavigationalBar, schemaEditor, timeMachine, filterPanel
+toolbar/     toolbar, toolbarButton, toolbarGroup, toolbarSeparator
+theme/       sceneTokenBridge.css
+properties.ts            narrow readers for the property bag
+cratisComponents.ts      the component registry
+cratisComponentsPackage.ts   the manifest and bundle
+```
+
+Adapters are prefixed `Scene` (`ScenePage`, `SceneDataTable`) because the wrapped components carry the same
+names — `Page`, `DataPage`, `Dialog` — and both live in the same file.
+
+## Property reading
+
+`properties.ts` is the only place a property-bag value is narrowed, and nothing casts. Each helper answers
+the same way: the value when it really is of the asked-for type, `undefined` otherwise, so an adapter reads a
+property and applies its own default in one expression.
+
+`stringProperty`, `booleanProperty`, `numberProperty`, `arrayProperty`, `stringArrayProperty`,
+`objectArrayProperty`, `objectProperty`, `unionProperty`.
+
+`unionProperty(properties, 'orientation', ['vertical', 'horizontal'] as const)` is what turns an authored
+string into one of a component's string-literal union props without an assertion.
+
+## Gates
+
+```bash
+npx tsc -b                 # from the repository root
+yarn build
+yarn test
+yarn lint:ci
+yarn build-storybook
+```
+
+Two notes on the Storybook and Vitest configuration, both worked around in this folder and both upstream
+issues rather than ours:
+
+- `@cratis/components@2.9.0` ships `dist/esm/TimeMachine/Properties.css` with `//` line comments, which are
+  not valid CSS. Vite 8's default lightningcss minifier rejects the whole bundle over it, so
+  `.storybook/main.ts` sets `cssMinify: 'esbuild'`.
+- `@cratis/components` and PrimeReact are published as ESM that still uses directory imports
+  (`primereact/api`), which Node's own resolver rejects. `vite.config.mts` inlines both so Vite resolves them
+  instead.

package/bindings/ArcRuntimeBoundary.tsx

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, Suspense } from 'react';
+import { ErrorBoundary } from '@cratis/components/Common';
+
+export interface ArcRuntimeBoundaryProps {
+    /** The lazily loaded, Arc-bound content this boundary isolates. */
+    children: ReactNode;
+}
+
+/**
+ * Isolates one Arc-bound component so that neither loading it nor failing to load it can take the
+ * surrounding screen down with it.
+ *
+ * The Arc-bound half of `@cratis/components` - `DataPage`, the data tables, `CommandForm` and its
+ * fields, every dialog - reaches `@cratis/arc` and `@cratis/arc.react` at import time. Those are peer
+ * dependencies the *host* supplies, and a design surface is not a host: Studio previews a screen without
+ * an Arc client, without a backend, and often without a single binding registered. This package
+ * therefore imports every Arc-bound component through a dynamic `import()` rather than a static one, so
+ * that a screen made only of the library's Arc-free components never pulls the Arc runtime in at all.
+ *
+ * That deferral has two visible states, and this covers both: `Suspense` while the chunk is in flight,
+ * and the library's own `ErrorBoundary` when it cannot be loaded - which is what a host without Arc
+ * installed will see. One dashed-out region, not a blank screen and not a thrown render.
+ *
+ * `ErrorBoundary` is used by composition rather than by writing another one: an error boundary is the
+ * one thing React still requires a class for, and `@cratis/components` already ships that class.
+ */
+export function ArcRuntimeBoundary({ children }: ArcRuntimeBoundaryProps) {
+    return (
+        <ErrorBoundary>
+            <Suspense fallback={<span data-scene-arc-loading=''>Loading</span>}>{children}</Suspense>
+        </ErrorBoundary>
+    );
+}

package/bindings/BindingKind.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a name in a screen is expected to resolve to when it is looked up in the binding registry.
+ *
+ * Queries and commands are kept apart rather than sharing one namespace because they are opposite halves
+ * of CQRS and a screen means exactly one of them at each site: `data Invoices via query AllInvoices`
+ * cannot be satisfied by a command of the same name, and letting it be satisfied would turn a modeling
+ * mistake into a runtime one.
+ */
+export enum BindingKind {
+    /** An Arc query proxy - what a data table or data page reads its rows from. */
+    Query = 'query',
+
+    /** An Arc command proxy - what a command form or command dialog submits. */
+    Command = 'command',
+}

package/bindings/BoundConstructor.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * A class a host registers under a name - an Arc query or command proxy, as generated from the backend's
+ * `[ReadModel]` and `[Command]` types.
+ *
+ * `@cratis/components` types these as `Constructor<T>` from `@cratis/fundamentals`, constrained to
+ * `IQueryFor<T>` / a command shape. This package cannot use those types: `@cratis/arc` and
+ * `@cratis/fundamentals` are peer dependencies of `@cratis/components` that the *host* provides, and
+ * Scene deliberately does not depend on Arc - a Scene screen is a UI model, and the whole point of the
+ * registry is that Scene never needs to know what an Arc proxy is.
+ *
+ * So the registry stores the widest honest shape: something that can be constructed. Whether a
+ * registered class really is a query or a command is the host's responsibility, and it is checkable
+ * where the host registers it, with the real Arc types in scope - which is exactly where it should be.
+ *
+ * `never[]` rather than `unknown[]` for the parameters so that any constructor is assignable, regardless
+ * of what it takes; `unknown[]` would only accept constructors whose parameters accept anything.
+ */
+export type BoundConstructor = new (...args: never[]) => object;

package/bindings/ElementBinding.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BoundConstructor } from './BoundConstructor';
+
+/**
+ * What a screen asked for at a binding site, and what the registry could actually produce for it.
+ *
+ * The name is kept even when nothing resolved, because the two failure modes an adapter has to
+ * distinguish - "the screen named something that is not registered" and "the screen named nothing" -
+ * are only tellable apart by whether a name is present.
+ */
+export interface ElementBinding {
+    /** The name the screen wrote, or `undefined` when the screen set no binding property at all. */
+    name?: string;
+
+    /** The registered class, or `undefined` when nothing is registered under {@link name}. */
+    target?: BoundConstructor;
+}

package/bindings/MissingBinding.tsx

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent } from '@cratis/scene.model';
+import { BindingKind } from './BindingKind';
+import { Placeholder } from './Placeholder';
+
+export interface MissingBindingProps {
+    /** The element whose binding could not be satisfied. */
+    element: ExternalComponent;
+
+    /** Whether a query or a command was wanted. */
+    kind: BindingKind;
+
+    /**
+     * The name the screen asked for, or `undefined` when the screen never named one. The two are
+     * different mistakes and get different messages - a screen that names `AllInvoices` needs the host
+     * to register it, while a screen that names nothing needs editing.
+     */
+    name?: string;
+}
+
+/**
+ * The placeholder an Arc-bound adapter renders instead of its real component when the binding it needs
+ * is not available.
+ *
+ * It names the binding, because that is the only actionable part: the fix is either to register that
+ * name in the host or to correct the name in the screen, and the message has to be enough to tell those
+ * two apart without opening a debugger.
+ */
+export function MissingBinding({ element, kind, name }: MissingBindingProps) {
+    const problem = name === undefined ? `Missing ${kind} binding` : `Unresolved ${kind} binding '${name}'`;
+    return <Placeholder element={element} problem={problem} />;
+}