@dxos/plugin-markdown 0.8.4-main.67995b8 → 0.8.4-main.dedc0f3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-markdown",
-  "version": "0.8.4-main.67995b8",
+  "version": "0.8.4-main.dedc0f3",
   "description": "DXOS Surface plugin for interacting with Markdown",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,16 +10,16 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs",
-      "source": "./src/index.ts"
+      "node": "./dist/lib/node-esm/index.mjs"
     },
     "./types": {
+      "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
       "browser": "./dist/lib/browser/types/index.mjs",
-      "node": "./dist/lib/node-esm/types/index.mjs",
-      "source": "./src/types/index.ts"
+      "node": "./dist/lib/node-esm/types/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -36,56 +36,59 @@
   ],
   "dependencies": {
     "@automerge/automerge": "3.1.1",
-    "@codemirror/search": "^6.5.6",
-    "@codemirror/view": "^6.34.1",
+    "@codemirror/search": "^6.5.11",
+    "@codemirror/view": "^6.38.2",
+    "@effect/ai": "0.25.2",
     "@preact-signals/safe-react": "^0.9.0",
     "@preact/signals-core": "^1.9.0",
     "react-dropzone": "^14.2.3",
-    "@dxos/app-framework": "0.8.4-main.67995b8",
-    "@dxos/ai": "0.8.4-main.67995b8",
-    "@dxos/async": "0.8.4-main.67995b8",
-    "@dxos/assistant": "0.8.4-main.67995b8",
-    "@dxos/blueprints": "0.8.4-main.67995b8",
-    "@dxos/echo": "0.8.4-main.67995b8",
-    "@dxos/echo-schema": "0.8.4-main.67995b8",
-    "@dxos/invariant": "0.8.4-main.67995b8",
-    "@dxos/keys": "0.8.4-main.67995b8",
-    "@dxos/lit-ui": "0.8.4-main.67995b8",
-    "@dxos/local-storage": "0.8.4-main.67995b8",
-    "@dxos/log": "0.8.4-main.67995b8",
-    "@dxos/plugin-attention": "0.8.4-main.67995b8",
-    "@dxos/live-object": "0.8.4-main.67995b8",
-    "@dxos/plugin-client": "0.8.4-main.67995b8",
-    "@dxos/plugin-deck": "0.8.4-main.67995b8",
-    "@dxos/plugin-graph": "0.8.4-main.67995b8",
-    "@dxos/plugin-preview": "0.8.4-main.67995b8",
-    "@dxos/plugin-theme": "0.8.4-main.67995b8",
-    "@dxos/react-hooks": "0.8.4-main.67995b8",
-    "@dxos/react-client": "0.8.4-main.67995b8",
-    "@dxos/react-ui-attention": "0.8.4-main.67995b8",
-    "@dxos/plugin-space": "0.8.4-main.67995b8",
-    "@dxos/react-ui-editor": "0.8.4-main.67995b8",
-    "@dxos/react-ui-form": "0.8.4-main.67995b8",
-    "@dxos/react-ui-stack": "0.8.4-main.67995b8",
-    "@dxos/schema": "0.8.4-main.67995b8",
-    "@dxos/util": "0.8.4-main.67995b8"
+    "@dxos/ai": "0.8.4-main.dedc0f3",
+    "@dxos/app-framework": "0.8.4-main.dedc0f3",
+    "@dxos/assistant": "0.8.4-main.dedc0f3",
+    "@dxos/async": "0.8.4-main.dedc0f3",
+    "@dxos/echo": "0.8.4-main.dedc0f3",
+    "@dxos/blueprints": "0.8.4-main.dedc0f3",
+    "@dxos/echo-db": "0.8.4-main.dedc0f3",
+    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
+    "@dxos/functions": "0.8.4-main.dedc0f3",
+    "@dxos/invariant": "0.8.4-main.dedc0f3",
+    "@dxos/lit-ui": "0.8.4-main.dedc0f3",
+    "@dxos/keys": "0.8.4-main.dedc0f3",
+    "@dxos/live-object": "0.8.4-main.dedc0f3",
+    "@dxos/local-storage": "0.8.4-main.dedc0f3",
+    "@dxos/log": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-attention": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-client": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-deck": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-graph": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-preview": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-theme": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-space": "0.8.4-main.dedc0f3",
+    "@dxos/react-client": "0.8.4-main.dedc0f3",
+    "@dxos/react-hooks": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-attention": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-editor": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-form": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-stack": "0.8.4-main.dedc0f3",
+    "@dxos/schema": "0.8.4-main.dedc0f3",
+    "@dxos/util": "0.8.4-main.dedc0f3"
   },
   "devDependencies": {
     "@effect-rx/rx-react": "0.38.0",
-    "@effect/platform": "0.89.0",
+    "@effect/platform": "0.90.2",
     "@types/react": "~18.2.0",
     "@types/react-dom": "~18.2.0",
-    "effect": "3.17.0",
+    "effect": "3.17.7",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "vite": "5.4.7",
-    "@dxos/debug": "0.8.4-main.67995b8",
-    "@dxos/plugin-storybook-layout": "0.8.4-main.67995b8",
-    "@dxos/plugin-theme": "0.8.4-main.67995b8",
-    "@dxos/random": "0.8.4-main.67995b8",
-    "@dxos/react-ui": "0.8.4-main.67995b8",
-    "@dxos/react-ui-theme": "0.8.4-main.67995b8",
-    "@dxos/storybook-utils": "0.8.4-main.67995b8"
+    "vite": "7.1.1",
+    "@dxos/plugin-storybook-layout": "0.8.4-main.dedc0f3",
+    "@dxos/debug": "0.8.4-main.dedc0f3",
+    "@dxos/plugin-theme": "0.8.4-main.dedc0f3",
+    "@dxos/random": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3",
+    "@dxos/storybook-utils": "0.8.4-main.dedc0f3"
   },
   "peerDependencies": {
     "@effect-rx/rx-react": "^0.34.1",
@@ -93,8 +96,8 @@
     "effect": "^3.13.3",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.4-main.67995b8",
-    "@dxos/react-ui-theme": "0.8.4-main.67995b8"
+    "@dxos/react-ui": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3"
   },
   "publishConfig": {
     "access": "public"

package/src/MarkdownPlugin.tsx

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes, createIntent, defineModule, definePlugin, Events } from '@dxos/app-framework';
+import { Capabilities, Events, contributes, createIntent, defineModule, definePlugin } from '@dxos/app-framework';
 import { type Obj, Ref } from '@dxos/echo';
 import { ClientCapabilities, ClientEvents } from '@dxos/plugin-client';
 import { SpaceCapabilities } from '@dxos/plugin-space';
@@ -14,11 +14,13 @@ import { DataType } from '@dxos/schema';
 import {
   AnchorSort,
   AppGraphSerializer,
-  ArtifactDefinition,
+  BLUEPRINT_KEY,
+  BlueprintDefinition,
   IntentResolver,
-  MarkdownState,
   MarkdownSettings,
+  MarkdownState,
   ReactSurface,
+  Toolkit,
 } from './capabilities';
 import { MarkdownEvents } from './events';
 import { meta } from './meta';
@@ -55,6 +57,7 @@ export const MarkdownPlugin = () =>
           metadata: {
             label: (object: Markdown.Document) => object.name || object.fallbackName,
             icon: 'ph--text-aa--regular',
+            blueprints: [BLUEPRINT_KEY],
             graphProps: {
               managesAutofocus: true,
             },
@@ -81,7 +84,7 @@ export const MarkdownPlugin = () =>
           SpaceCapabilities.ObjectForm,
           defineObjectForm({
             objectSchema: Markdown.Document,
-            getIntent: (_, { space }) => createIntent(MarkdownAction.Create, { spaceId: space.id }),
+            getIntent: () => createIntent(MarkdownAction.Create, {}),
           }),
         ),
     }),
@@ -114,8 +117,14 @@ export const MarkdownPlugin = () =>
       activate: AnchorSort,
     }),
     defineModule({
-      id: `${meta.id}/module/artifact-definition`,
+      id: `${meta.id}/module/blueprint`,
       activatesOn: Events.SetupArtifactDefinition,
-      activate: ArtifactDefinition,
+      activate: BlueprintDefinition,
+    }),
+    defineModule({
+      id: `${meta.id}/module/toolkit`,
+      // TODO(wittjosiah): Use a different event.
+      activatesOn: Events.Startup,
+      activate: Toolkit,
     }),
   ]);

package/src/capabilities/app-graph-serializer.ts

@@ -4,7 +4,7 @@
 
 import { pipe } from 'effect';
 
-import { contributes, Capabilities, type PluginContext, chain, createIntent } from '@dxos/app-framework';
+import { Capabilities, type PluginContext, chain, contributes, createIntent } from '@dxos/app-framework';
 import { Obj } from '@dxos/echo';
 import { SpaceAction } from '@dxos/plugin-space/types';
 import { isSpace } from '@dxos/react-client/echo';
@@ -43,7 +43,7 @@ export default (context: PluginContext) =>
         const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
         const result = await dispatch(
           pipe(
-            createIntent(MarkdownAction.Create, { spaceId: space.id, name: data.name, content: data.data }),
+            createIntent(MarkdownAction.Create, { name: data.name, content: data.data }),
             chain(SpaceAction.AddObject, { target }),
           ),
         );

package/src/capabilities/artifact-definition.ts

@@ -2,36 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import { pipe, Schema } from 'effect';
+// ISSUE(burdon): defineArtifact
+// @ts-nocheck
 
-import { createTool, ToolResult } from '@dxos/ai';
-import { Capabilities, chain, contributes, createIntent, type PromiseIntentDispatcher } from '@dxos/app-framework';
-import { createArtifactElement, ArtifactId } from '@dxos/assistant';
+import { Schema, pipe } from 'effect';
+
+import { ToolResult, createTool } from '@dxos/ai';
+import { Capabilities, chain, contributes, createIntent } from '@dxos/app-framework';
+import { ArtifactId, createArtifactElement } from '@dxos/assistant';
 import { defineArtifact } from '@dxos/blueprints';
 import { Obj } from '@dxos/echo';
-import { invariant, assertArgument } from '@dxos/invariant';
+import { assertArgument, invariant } from '@dxos/invariant';
 import { SpaceAction } from '@dxos/plugin-space/types';
-import { Filter, fullyQualifiedId, type Space } from '@dxos/react-client/echo';
+import { Filter, fullyQualifiedId } from '@dxos/react-client/echo';
 
 import { meta } from '../meta';
 import { Markdown, MarkdownAction } from '../types';
 
-// TODO(burdon): Factor out.
-declare global {
-  interface ToolContextExtensions {
-    space?: Space;
-    dispatch?: PromiseIntentDispatcher;
-  }
-}
-
 export default () => {
   const definition = defineArtifact({
     id: `artifact:${meta.id}`, // TODO(burdon): meta.id/artifact?
     name: meta.name,
     instructions: `
-      - The markdown plugin allows you to work with text documents in the current space.
-      - Use these tools to interact with documents, including listing available documents and retrieving their content.
-      - Documents are stored in Markdown format.
+      The markdown plugin allows you to work with text documents in the current space.
+      Use these tools to interact with documents, including listing available documents and retrieving their content.
+      Documents are stored in Markdown format.
     `,
     schema: Markdown.Document,
     tools: [
@@ -99,7 +94,7 @@ export default () => {
         execute: async ({ id }, { extensions }) => {
           invariant(extensions?.space, 'No space');
           const document = await extensions.space.db.query(Filter.ids(ArtifactId.toDXN(id).toString())).first();
-          assertArgument(Obj.instanceOf(Markdown.Document, document), 'Invalid type');
+          assertArgument(Obj.instanceOf(Markdown.Document, document), 'document', 'Invalid type');
 
           const { content } = await document.content?.load();
           return ToolResult.Success({

package/src/capabilities/blueprint-definition.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, type Capability, contributes } from '@dxos/app-framework';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { type FunctionDefinition } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+import { diff, open } from '../functions';
+
+const functions: FunctionDefinition[] = [diff, open];
+const tools = ['add-proposals', 'create-document'];
+
+export const BLUEPRINT_KEY = 'dxos.org/blueprint/markdown';
+
+export default (): Capability<any>[] => [
+  contributes(Capabilities.Functions, functions),
+  contributes(
+    Capabilities.BlueprintDefinition,
+    Blueprint.make({
+      key: BLUEPRINT_KEY,
+      name: 'Markdown',
+      tools: Blueprint.toolDefinitions({ functions, tools }),
+      instructions: Template.make({
+        source: trim`
+            You can create and update markdown documents.
+            When asked to edit or update documents return updates as a set of compact diff string pairs.
+            For each diff, respond with the smallest possible matching span.
+            For example:
+            - "There is a tyop in this sentence."
+            + "There is a typo in this sentence."
+            - "This id goof."
+            + "This is good."
+          `,
+      }),
+    }),
+  ),
+];

package/src/capabilities/capabilities.ts

@@ -3,7 +3,7 @@
 //
 
 import { defineCapability } from '@dxos/app-framework';
-import { type EditorViewMode, type EditorStateStore } from '@dxos/react-ui-editor';
+import { type EditorStateStore, type EditorViewMode } from '@dxos/react-ui-editor';
 
 import { meta } from '../meta';
 import { type MarkdownExtensionProvider, type MarkdownPluginState } from '../types';

package/src/capabilities/index.ts

@@ -6,10 +6,12 @@ import { lazy } from '@dxos/app-framework';
 
 export const AnchorSort = lazy(() => import('./anchor-sort'));
 export const AppGraphSerializer = lazy(() => import('./app-graph-serializer'));
-export const ArtifactDefinition = lazy(() => import('./artifact-definition'));
+export const BlueprintDefinition = lazy(() => import('./blueprint-definition'));
 export const IntentResolver = lazy(() => import('./intent-resolver'));
 export const ReactSurface = lazy(() => import('./react-surface'));
 export const MarkdownSettings = lazy(() => import('./settings'));
 export const MarkdownState = lazy(() => import('./state'));
+export const Toolkit = lazy(() => import('./toolkit'));
 
+export * from './blueprint-definition';
 export * from './capabilities';

package/src/capabilities/intent-resolver.ts

@@ -3,21 +3,22 @@
 //
 
 import { next as A } from '@automerge/automerge';
-import { Option, pipe, type Schema } from 'effect';
+import { Option, type Schema } from 'effect';
 
 import {
   Capabilities,
   CollaborationActions,
+  type PluginContext,
   contributes,
   createResolver,
-  type PluginContext,
 } from '@dxos/app-framework';
 import { Obj } from '@dxos/echo';
 import { createDocAccessor, getRangeFromCursor } from '@dxos/react-client/echo';
 
-import { MarkdownCapabilities } from './capabilities';
 import { Markdown, MarkdownAction } from '../types';
 
+import { MarkdownCapabilities } from './capabilities';
+
 export default (context: PluginContext) =>
   contributes(Capabilities.IntentResolver, [
     createResolver({
@@ -34,23 +35,22 @@ export default (context: PluginContext) =>
       },
     }),
     createResolver({
-      intent: CollaborationActions.InsertContent,
+      intent: CollaborationActions.AcceptProposal,
       filter: (
         data,
-      ): data is Omit<Schema.Schema.Type<typeof CollaborationActions.InsertContent.fields.input>, 'target'> & {
-        target: Markdown.Document;
-      } => Obj.instanceOf(Markdown.Document, data.target),
-      resolve: async ({ target, object: objectRef, at, label }) => {
-        const text = await target.content.load();
+      ): data is Omit<Schema.Schema.Type<typeof CollaborationActions.AcceptProposal.fields.input>, 'subject'> & {
+        subject: Markdown.Document;
+      } => Obj.instanceOf(Markdown.Document, data.subject),
+      resolve: async ({ subject, anchor, proposal }) => {
+        const text = await subject.content.load();
         const accessor = createDocAccessor(text, ['content']);
-        const { start, end } = pipe(
-          Option.fromNullable(at),
+        const { start, end } = Option.fromNullable(anchor).pipe(
           Option.flatMap((at) => Option.fromNullable(getRangeFromCursor(accessor, at))),
+          // Fallback to the end of the document.
           Option.getOrElse(() => ({ start: text.content.length - 1, end: text.content.length - 1 })),
         );
         accessor.handle.change((doc) => {
-          const ref = `[${label ?? 'Generated content'}]](${objectRef.dxn.toString()})\n`;
-          A.splice(doc, accessor.path.slice(), start, end - start, ref);
+          A.splice(doc, accessor.path.slice(), start, end - start, proposal.text);
         });
       },
     }),

package/src/capabilities/react-surface.tsx

@@ -4,19 +4,20 @@
 
 import React from 'react';
 
-import { createSurface, contributes, Capabilities, useCapability } from '@dxos/app-framework';
+import { Capabilities, contributes, createSurface, useCapability } from '@dxos/app-framework';
 import { Obj } from '@dxos/echo';
 import { SettingsStore } from '@dxos/local-storage';
 import { AttentionCapabilities } from '@dxos/plugin-attention';
 import { fullyQualifiedId } from '@dxos/react-client/echo';
 import { DataType } from '@dxos/schema';
 
-import { MarkdownCapabilities } from './capabilities';
-import { MarkdownContainer, MarkdownSettings, MarkdownPreview } from '../components';
+import { MarkdownCard, MarkdownContainer, MarkdownSettings } from '../components';
 import { meta } from '../meta';
 import { Markdown } from '../types';
 import { isEditorModel } from '../util';
 
+import { MarkdownCapabilities } from './capabilities';
+
 export default () =>
   contributes(Capabilities.ReactSurface, [
     createSurface({
@@ -109,6 +110,6 @@ export default () =>
       role: ['card--popover', 'card--intrinsic', 'card--extrinsic', 'card--transclusion', 'card'],
       filter: (data): data is { subject: Markdown.Document | DataType.Text } =>
         Obj.instanceOf(Markdown.Document, data.subject) || Obj.instanceOf(DataType.Text, data.subject),
-      component: ({ data, role }) => <MarkdownPreview {...data} role={role} />,
+      component: ({ data, role }) => <MarkdownCard {...data} role={role} />,
     }),
   ]);

package/src/capabilities/state.ts

@@ -2,14 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes, type PluginContext } from '@dxos/app-framework';
+import { Capabilities, type PluginContext, contributes } from '@dxos/app-framework';
 import { LocalStorageStore } from '@dxos/local-storage';
 import { type EditorViewMode, createEditorStateStore } from '@dxos/react-ui-editor';
 
-import { MarkdownCapabilities } from './capabilities';
 import { meta } from '../meta';
 import { type Markdown, type MarkdownPluginState } from '../types';
 
+import { MarkdownCapabilities } from './capabilities';
+
 export default (context: PluginContext) => {
   const state = new LocalStorageStore<MarkdownPluginState>(meta.id, { extensionProviders: [], viewMode: {} });
   state.prop({ key: 'viewMode', type: LocalStorageStore.json<{ [key: string]: EditorViewMode }>() });

package/src/capabilities/toolkit.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { AiTool, AiToolkit } from '@effect/ai';
+import { Effect, Schema } from 'effect';
+
+import { Capabilities, type Capability, type PluginContext, contributes, createIntent } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+import { getActiveSpace } from '@dxos/plugin-space';
+import { SpaceAction } from '@dxos/plugin-space/types';
+
+import { MarkdownAction } from '../types';
+
+// TODO(burdon): Reconcile with functions (currently reuses plugin framework intents).
+class Toolkit extends AiToolkit.make(
+  AiTool.make('create-document', {
+    description: 'Creates a new markdown document.',
+    parameters: {
+      name: Schema.optional(Schema.String),
+      content: Schema.optional(Schema.String),
+    },
+    // TODO(wittjosiah): Return document.
+    success: Schema.Any,
+    failure: Schema.Never,
+  }),
+) {
+  static layer = (context: PluginContext) =>
+    Toolkit.toLayer({
+      'create-document': ({ name, content }) => {
+        const { dispatch } = context.getCapability(Capabilities.IntentDispatcher);
+        const space = getActiveSpace(context);
+        invariant(space, 'No active space');
+
+        return Effect.gen(function* () {
+          const { object } = yield* dispatch(createIntent(MarkdownAction.Create, { name, content }));
+          yield* dispatch(createIntent(SpaceAction.AddObject, { object, target: space }));
+          return { id: object.id };
+        }).pipe(Effect.orDie);
+      },
+    });
+}
+
+export default (context: PluginContext): Capability<any>[] => [
+  contributes(Capabilities.Toolkit, Toolkit),
+  contributes(Capabilities.ToolkitHandler, Toolkit.layer(context)),
+];

package/src/components/{MarkdownPreview/MarkdownPreview.stories.tsx → MarkdownCard/MarkdownCard.stories.tsx}

@@ -4,7 +4,7 @@
 
 import '@dxos-theme';
 
-import { type StoryObj, type Meta } from '@storybook/react-vite';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { IntentPlugin } from '@dxos/app-framework';
@@ -12,20 +12,21 @@ import { withPluginManager } from '@dxos/app-framework/testing';
 import { Markdown } from '@dxos/plugin-markdown/types';
 import { faker } from '@dxos/random';
 import { CardContainer } from '@dxos/react-ui-stack/testing';
-import { withTheme, withLayout } from '@dxos/storybook-utils';
+import { withLayout, withTheme } from '@dxos/storybook-utils';
 
-import { MarkdownPreview } from './MarkdownPreview';
 import { translations } from '../../translations';
 
+import { MarkdownCard } from './MarkdownCard';
+
 faker.seed(1234);
 
-const meta: Meta<typeof MarkdownPreview> = {
-  title: 'Cards/plugin-markdown',
-  component: MarkdownPreview,
+const meta: Meta<typeof MarkdownCard> = {
+  title: 'plugins/plugin-markdown/Card',
+  component: MarkdownCard,
   render: ({ role, subject, ...args }) => {
     return (
       <CardContainer icon='ph--text-aa--regular' role={role}>
-        <MarkdownPreview role={role} subject={subject} {...args} />
+        <MarkdownCard role={role} subject={subject} {...args} />
       </CardContainer>
     );
   },
@@ -40,7 +41,8 @@ const meta: Meta<typeof MarkdownPreview> = {
     layout: 'centered',
     translations,
   },
-};
+  tags: ['cards'],
+} satisfies Meta<typeof MarkdownCard>;
 
 export default meta;
 
@@ -56,9 +58,9 @@ export const Popover: Story = {
   },
 };
 
-export const Extrinsic: Story = {
+export const Intrinsic: Story = {
   args: {
-    role: 'card--extrinsic',
+    role: 'card--intrinsic',
     subject: Markdown.makeDocument({
       name: faker.lorem.words(3),
       content: faker.lorem.paragraphs(3),
@@ -66,9 +68,9 @@ export const Extrinsic: Story = {
   },
 };
 
-export const Intrinsic: Story = {
+export const Extrinsic: Story = {
   args: {
-    role: 'card--intrinsic',
+    role: 'card--extrinsic',
     subject: Markdown.makeDocument({
       name: faker.lorem.words(3),
       content: faker.lorem.paragraphs(3),

package/src/components/{MarkdownPreview/MarkdownPreview.tsx → MarkdownCard/MarkdownCard.tsx}

@@ -5,7 +5,7 @@
 import { pipe } from 'effect';
 import React, { useCallback } from 'react';
 
-import { chain, createIntent, LayoutAction, useIntentDispatcher } from '@dxos/app-framework';
+import { LayoutAction, chain, createIntent, useIntentDispatcher } from '@dxos/app-framework';
 import { Obj } from '@dxos/echo';
 import { type PreviewProps } from '@dxos/plugin-preview';
 import { fullyQualifiedId } from '@dxos/react-client/echo';
@@ -35,7 +35,9 @@ const getSnippet = (subject: Markdown.Document | DataType.Text, fallback: string
   }
 };
 
-export const MarkdownPreview = ({ subject, role }: PreviewProps<Markdown.Document | DataType.Text>) => {
+export type MarkdownCardProps = PreviewProps<Markdown.Document | DataType.Text>;
+
+export const MarkdownCard = ({ subject, role }: MarkdownCardProps) => {
   const { dispatchPromise: dispatch } = useIntentDispatcher();
   const { t } = useTranslation(meta.id);
   const snippet = getSnippet(subject, t('fallback abstract'));

package/src/components/MarkdownCard/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { MarkdownCard } from './MarkdownCard';
+
+export * from './MarkdownCard';
+
+export default MarkdownCard;

package/src/components/MarkdownContainer.stories.tsx

@@ -4,10 +4,10 @@
 
 import '@dxos-theme';
 
-import { type Meta } from '@storybook/react-vite';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useMemo } from 'react';
 
-import { Capabilities, contributes, IntentPlugin, SettingsPlugin, Surface } from '@dxos/app-framework';
+import { Capabilities, IntentPlugin, SettingsPlugin, Surface, contributes } from '@dxos/app-framework';
 import { withPluginManager } from '@dxos/app-framework/testing';
 import { todo } from '@dxos/debug';
 import { Query, Type } from '@dxos/echo';
@@ -22,7 +22,7 @@ import { faker } from '@dxos/random';
 import { useQuery, useSpace } from '@dxos/react-client/echo';
 import { defaultTx } from '@dxos/react-ui-theme';
 import { DataType } from '@dxos/schema';
-import { createObjectFactory, Testing, type ValueGenerator } from '@dxos/schema/testing';
+import { Testing, type ValueGenerator, createObjectFactory } from '@dxos/schema/testing';
 import { withLayout } from '@dxos/storybook-utils';
 
 import { MarkdownPlugin } from '../MarkdownPlugin';
@@ -41,7 +41,7 @@ const DefaultStory = () => {
   return <Surface role='article' data={data} />;
 };
 
-const meta: Meta<typeof DefaultStory> = {
+const meta = {
   title: 'plugins/plugin-markdown/MarkdownContainer',
   render: DefaultStory,
   decorators: [
@@ -52,7 +52,7 @@ const meta: Meta<typeof DefaultStory> = {
         StorybookLayoutPlugin(),
         ClientPlugin({
           types: [Markdown.Document, DataType.Text, Testing.Contact],
-          onClientInitialized: async (_, client) => {
+          onClientInitialized: async ({ client }) => {
             await client.halo.createIdentity();
             await client.spaces.waitUntilReady();
             await client.spaces.default.waitUntilReady();
@@ -91,10 +91,10 @@ const meta: Meta<typeof DefaultStory> = {
     translations,
     controls: { disable: true },
   },
-};
+} satisfies Meta<typeof Capabilities>;
 
 export default meta;
 
-type Story = Meta<typeof DefaultStory>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};