@djangocfg/widget-editor 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @djangocfg/widget-editor
+
+Two TipTap editors and the pieces both are built from.
+
+| Subpath | What | Own docs |
+|---|---|---|
+| `./markdown` | `MarkdownEditor` — a markdown field with mentions, URL and file-path chips | [`src/markdown/README.md`](src/markdown/README.md) |
+| `./notion` | `NotionEditor` — a block editor: slash menu, tables, tasks, code, bookmarks, maps | [`src/notion/README.md`](src/notion/README.md), [`@docs/`](src/notion/@docs/) |
+| `./blocks` | The zod schemas for the embeddable block payloads | — |
+| `./link-preview` | `LinkPreviewCard` and the `ResolveLinkPreview` seam | — |
+| `./chips` | `UrlChip`, `FilePathChip` — the same pills outside an editor | [`src/chips/README.md`](src/chips/README.md) |
+| `./tiptap` | `useNodeAttrs` and the node-view helpers | — |
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-editor @djangocfg/ui-core zod
+```
+
+`zod` is a peer: the block schemas validate payloads a host also validates, and
+two copies would reject each other's instances.
+
+## There is no root barrel worth importing
+
+The root exports a type and nothing else, on purpose. TipTap is sixteen
+packages, and the two editors share no consumer — an app wanting the markdown
+field must not resolve the Notion editor's tables, drag handle and syntax
+highlighter behind it. **Import a subpath.**
+
+## The map block is a real dependency
+
+`NotionEditor`'s `mapBlock` renders `@djangocfg/widget-map`, so the editor
+depends on the map widget rather than the other way round. It arrives through
+the map's lazy entry, so MapLibre still loads only when a map block mounts.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-editor check-types test
+```

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@djangocfg/widget-editor",
+  "version": "0.1.1",
+  "description": "TipTap editors: a markdown field with mentions and chips, and a Notion-style block editor with slash commands, tables and embedded blocks",
+  "keywords": [
+    "editor",
+    "tiptap",
+    "markdown",
+    "wysiwyg",
+    "notion",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/editor"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./markdown": {
+      "types": "./src/markdown/lazy.tsx",
+      "default": "./src/markdown/lazy.tsx"
+    },
+    "./notion": {
+      "types": "./src/notion/lazy.tsx",
+      "default": "./src/notion/lazy.tsx"
+    },
+    "./blocks": {
+      "types": "./src/blocks/index.ts",
+      "default": "./src/blocks/index.ts"
+    },
+    "./link-preview": {
+      "types": "./src/link-preview/index.ts",
+      "default": "./src/link-preview/index.ts"
+    },
+    "./chips": {
+      "types": "./src/chips/index.ts",
+      "default": "./src/chips/index.ts"
+    },
+    "./tiptap": {
+      "types": "./src/tiptap/index.ts",
+      "default": "./src/tiptap/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@djangocfg/widget-data": "^0.1.1",
+    "@djangocfg/widget-kit": "^0.1.1",
+    "@djangocfg/widget-map": "^0.1.1",
+    "@floating-ui/dom": "^1.8.0",
+    "@tiptap/core": "^3.27.3",
+    "@tiptap/extension-code-block-lowlight": "^3.27.3",
+    "@tiptap/extension-highlight": "^3.27.3",
+    "@tiptap/extension-mention": "^3.27.3",
+    "@tiptap/extension-placeholder": "^3.27.3",
+    "@tiptap/extension-table": "^3.27.3",
+    "@tiptap/extension-table-cell": "^3.27.3",
+    "@tiptap/extension-table-header": "^3.27.3",
+    "@tiptap/extension-table-row": "^3.27.3",
+    "@tiptap/extension-task-item": "^3.27.3",
+    "@tiptap/extension-task-list": "^3.27.3",
+    "@tiptap/markdown": "^3.27.3",
+    "@tiptap/pm": "^3.27.3",
+    "@tiptap/react": "^3.27.3",
+    "@tiptap/starter-kit": "^3.27.3",
+    "@tiptap/suggestion": "^3.27.3",
+    "lowlight": "^3.3.0",
+    "tiptap-extension-global-drag-handle": "^0.1.18"
+  },
+  "peerDependencies": {
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "storybook": "^10.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/blocks/BlockError.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+/**
+ * `<BlockError>` — the safe presentational fallback a data-driven block renders
+ * when its payload fails schema validation (a corrupted ```map JSON, a
+ * malformed wire block). Informative, not scary: a compact muted card that says
+ * the block couldn't render, with an optional short reason. Never throws, so the
+ * surrounding editor / message list stays alive.
+ *
+ * Semantic tokens only (`bg-muted` / `border-border` / `text-muted-foreground`).
+ */
+
+import { AlertTriangle } from 'lucide-react';
+
+export interface BlockErrorProps {
+  /**
+   * Short, human-readable reason (e.g. the first Zod issue). Optional — when
+   * omitted only the generic headline shows.
+   */
+  reason?: string;
+  /** What couldn't be rendered (e.g. "map", "bookmark"). Defaults to "block". */
+  label?: string;
+  className?: string;
+}
+
+export function BlockError({ reason, label = 'block', className }: BlockErrorProps) {
+  return (
+    <div
+      role="status"
+      className={
+        'flex items-start gap-2.5 rounded-lg border border-border bg-muted px-3 py-2.5 text-sm text-muted-foreground' +
+        (className ? ` ${className}` : '')
+      }
+    >
+      <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+      <div className="min-w-0">
+        <div className="font-medium text-foreground">Couldn&apos;t render this {label}</div>
+        {reason ? (
+          <div className="mt-0.5 break-words text-xs text-muted-foreground">{reason}</div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export default BlockError;

package/src/blocks/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared block payload types — the serializable wire shapes that both the
+ * chat message blocks and the NotionEditor block NodeViews reference, so the
+ * shapes can't drift. The link-preview data shape lives in
+ * `common/link-preview`; the map payload lives here. Re-exported below so a
+ * single import (`common/blocks`) reaches every shared block payload.
+ */
+
+export type {
+  MapBlockPayload,
+  MapMarkerPayload,
+  MapRoutePayload,
+  MapPolygonPayload,
+} from './types';
+
+// Re-export the link-preview data contract from its home so consumers can
+// reach every shared block payload from one place.
+export type { LinkPreviewData, ResolveLinkPreview } from '../link-preview';
+
+// Runtime validators + the safe-render fallback. A block NodeView/renderer
+// parses its payload through the matching schema and renders `<BlockError>`
+// on failure instead of throwing.
+export {
+  MapMarkerPayloadSchema,
+  MapRoutePayloadSchema,
+  MapPolygonPayloadSchema,
+  MapBlockPayloadSchema,
+  LinkPreviewDataSchema,
+  safeParseBlock,
+} from './schemas';
+export type { SafeParseResult } from './schemas';
+
+export { BlockError } from './BlockError';
+export type { BlockErrorProps } from './BlockError';

package/src/blocks/schemas.ts

@@ -0,0 +1,143 @@
+/**
+ * Zod schemas for the shared, serializable block payloads in `./types.ts` and
+ * the link-preview data contract. These are the runtime VALIDATORS that let a
+ * block NodeView render a safe `<BlockError>` fallback instead of throwing when
+ * it's handed a hand-authored / corrupted payload (a bad ```map JSON, a
+ * malformed wire block).
+ *
+ * The TS payload types stay the source of truth in `./types.ts` (and
+ * `common/link-preview/types.ts`); these schemas are kept in SYNC with them and
+ * `satisfies`-checked below so they can't silently drift. We deliberately do
+ * NOT re-export `z.infer` types under the same names — existing imports
+ * (`MapBlockPayload`, `LinkPreviewData`) keep coming from their type homes.
+ *
+ * Schemas are permissive on optional/extra fields (`.passthrough` is implied by
+ * Zod object stripping unknowns) but STRICT on the load-bearing shape: numbers
+ * are numbers, `center`/`url` are required. Anything that wouldn't render
+ * cleanly fails `safeParse`.
+ */
+
+import { z } from 'zod';
+import type {
+  MapMarkerPayload,
+  MapRoutePayload,
+  MapPolygonPayload,
+  MapBlockPayload,
+} from './types';
+import type { LinkPreviewData } from '../link-preview';
+
+/** A finite number — rejects NaN/Infinity that would break the map camera. */
+const finiteNumber = z.number().finite();
+
+/** `{ lat, lng }` — a geographic point; both finite numbers, required. */
+const LatLngSchema = z.object({
+  lat: finiteNumber,
+  lng: finiteNumber,
+});
+
+/** Marker info-card (pure JSON; `href`-only actions). */
+const MarkerCardSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  image: z.string().optional(),
+  badge: z.string().optional(),
+  actions: z
+    .array(z.object({ label: z.string(), href: z.string().optional() }))
+    .optional(),
+});
+
+/** A single map marker — pin + optional label / icon / colour / card. */
+export const MapMarkerPayloadSchema = z.object({
+  id: z.string(),
+  lat: finiteNumber,
+  lng: finiteNumber,
+  label: z.string().optional(),
+  icon: z.string().optional(),
+  color: z.string().optional(),
+  card: MarkerCardSchema.optional(),
+});
+
+/** An ordered polyline (route / path). */
+export const MapRoutePayloadSchema = z.object({
+  id: z.string(),
+  points: z.array(LatLngSchema),
+  color: z.string().optional(),
+  label: z.string().optional(),
+});
+
+/** A filled polygon (zone), auto-closed. */
+export const MapPolygonPayloadSchema = z.object({
+  id: z.string(),
+  points: z.array(LatLngSchema),
+  fillColor: z.string().optional(),
+  strokeColor: z.string().optional(),
+  label: z.string().optional(),
+});
+
+/** The serializable map payload — center + optional viewport + overlays. */
+export const MapBlockPayloadSchema = z.object({
+  center: LatLngSchema,
+  zoom: finiteNumber.optional(),
+  basemap: z.string().optional(),
+  terrain: z.boolean().optional(),
+  markers: z.array(MapMarkerPayloadSchema).optional(),
+  routes: z.array(MapRoutePayloadSchema).optional(),
+  polygons: z.array(MapPolygonPayloadSchema).optional(),
+});
+
+/** Resolved link-preview metadata — `url` required, rest optional. */
+export const LinkPreviewDataSchema = z.object({
+  url: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  image: z.string().optional(),
+  favicon: z.string().optional(),
+  siteName: z.string().optional(),
+});
+
+// ── Drift guards ──────────────────────────────────────────────────────────
+// A type-level assertion that each schema's inferred output is assignable to
+// the canonical TS payload type. If `./types.ts` and a schema diverge, the
+// corresponding `Extends<…>` resolves to `never` and the assignment fails to
+// compile — keeping the schemas and types in lockstep.
+type Extends<A, B> = A extends B ? true : never;
+const _markerOk: Extends<z.infer<typeof MapMarkerPayloadSchema>, MapMarkerPayload> = true;
+const _routeOk: Extends<z.infer<typeof MapRoutePayloadSchema>, MapRoutePayload> = true;
+const _polygonOk: Extends<z.infer<typeof MapPolygonPayloadSchema>, MapPolygonPayload> = true;
+const _mapOk: Extends<z.infer<typeof MapBlockPayloadSchema>, MapBlockPayload> = true;
+const _linkOk: Extends<z.infer<typeof LinkPreviewDataSchema>, LinkPreviewData> = true;
+// Reference the guards so `noUnusedLocals` stays happy without exporting them.
+void [_markerOk, _routeOk, _polygonOk, _mapOk, _linkOk];
+
+/**
+ * Discriminated result of a guarded parse — never throws.
+ *
+ * The mutually-exclusive `?: never` fields make narrowing robust: a plain
+ * `if (!r.ok)` flows into the error branch even when `T` is a deep object type
+ * (TS's discriminant else-narrowing otherwise mis-fires on very large `data`
+ * shapes). Callers can therefore use `!r.ok` / `r.ok` freely.
+ */
+export type SafeParseResult<T> =
+  | { ok: true; data: T; error?: never }
+  | { ok: false; error: string; data?: never };
+
+/**
+ * Validate `data` against `schema`, returning a discriminated result instead of
+ * throwing. On failure `error` is a short, human-readable reason (the first
+ * Zod issue) suitable for a `<BlockError reason=…>` card.
+ *
+ * The output type is taken from the schema (`z.infer`) so callers get the
+ * precisely-typed `data` on the success branch with no extra type argument.
+ */
+export function safeParseBlock<S extends z.ZodTypeAny>(
+  schema: S,
+  data: unknown,
+): SafeParseResult<z.infer<S>> {
+  const result = schema.safeParse(data);
+  if (result.success) return { ok: true, data: result.data };
+  const first = result.error.issues[0];
+  const reason = first
+    ? `${first.path.length ? first.path.map(String).join('.') + ': ' : ''}${first.message}`
+    : 'Invalid payload';
+  return { ok: false, error: reason };
+}

package/src/blocks/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared, serializable block payload TYPES — the wire shapes that more than
+ * one surface (chat message blocks + the NotionEditor block NodeViews) must
+ * agree on. Defining them ONCE here keeps the shapes from drifting: chat's
+ * `tools/chat/types/block.ts` and the Notion nodes both reference these.
+ *
+ * Plain JSON only (no Date / no functions / no React nodes) so payloads
+ * survive history persistence, SSE transport, AND TipTap node attrs +
+ * markdown round-trips.
+ */
+
+/** A single map marker — a pin plus optional label / icon / colour / card. */
+export interface MapMarkerPayload {
+  id: string;
+  lat: number;
+  lng: number;
+  label?: string;
+  /** Image URL rendered as the marker pin (rounded thumbnail). */
+  icon?: string;
+  /** CSS color for the default pin (ignored when `icon` is set). */
+  color?: string;
+  /**
+   * Info-card opened above the pin on click (Google-Maps style). Pure JSON —
+   * strings/URLs only; actions are `href`-only links (no `onClick`/`icon`,
+   * which can't cross the wire). Rendered by the map's default `MarkerCard`.
+   */
+  card?: {
+    title: string;
+    description?: string;
+    image?: string;
+    badge?: string;
+    actions?: Array<{ label: string; href?: string }>;
+  };
+}
+
+/** An ordered polyline (route / path). */
+export interface MapRoutePayload {
+  id: string;
+  points: Array<{ lat: number; lng: number }>;
+  color?: string;
+  label?: string;
+}
+
+/** A filled polygon (zone), auto-closed. */
+export interface MapPolygonPayload {
+  id: string;
+  points: Array<{ lat: number; lng: number }>;
+  fillColor?: string;
+  strokeColor?: string;
+  label?: string;
+}
+
+/**
+ * Serializable map payload shared by the chat `MapBlock` and the NotionEditor
+ * `mapBlock` node. A center + optional zoom / basemap / terrain / markers /
+ * routes / polygons. The chat block extends this with chat-only concerns
+ * (a `caption`, `userLocation` opt-in); the Notion node serializes this whole
+ * object to/from a fenced ```` ```map ```` JSON block.
+ */
+export interface MapBlockPayload {
+  center: { lat: number; lng: number };
+  zoom?: number;
+  /**
+   * Basemap style — a built-in key (`'light'`/`'dark'`/`'streets'` ·
+   * `'liberty'`/`'bright'`/`'positron'`) or a full style-JSON URL. When
+   * omitted the map uses its default basemap.
+   */
+  basemap?: string;
+  /** Enable 3D terrain + hillshade (free AWS Terrarium DEM, no key). */
+  terrain?: boolean;
+  markers?: MapMarkerPayload[];
+  /** Polylines (routes / paths). */
+  routes?: MapRoutePayload[];
+  /** Filled zones (polygons). */
+  polygons?: MapPolygonPayload[];
+}

package/src/chips/README.md

@@ -0,0 +1,67 @@
+# chips
+
+Surface-agnostic presentational "chips" — compact inline pills that render a
+URL or a file path with a favicon/icon + middle-ellipsis label. They match the
+TipTap composer's `editor-chip` look (see
+[`forms/MarkdownEditor/chip/ChipNode.ts`](../../tools/forms/MarkdownEditor/chip/ChipNode.ts))
+but are plain React, so the same visual is reusable on any surface — composer,
+chat bubble, link lists.
+
+Internal module (`src/common/chips/`) — consumed by other tools via relative
+import; not a package subpath export:
+
+```tsx
+import { UrlChip, FilePathChip } from '../../common/chips';
+```
+
+## `UrlChip`
+
+A compact, clickable URL chip (Chrome-omnibox style): a favicon + the domain
+with a middle-ellipsised path (`github.com/wailsapp/…/README.md`), monospace,
+with the full href on `title` hover. Renders an `<a target="_blank"
+rel="noopener noreferrer">`, so it opens in a new tab.
+
+- **Favicon fallback.** The favicon `<img>` swaps to a lucide `Globe` glyph on
+  load error (offline / blocked / unknown host) — and also when the host is
+  unparseable (empty favicon URL) — so the chip never shows a broken image.
+- **Presentational + self-contained.** It imports only the pure URL detector
+  helpers from [`forms/MarkdownEditor/url/detect`](../../tools/forms/MarkdownEditor/url/detect.ts)
+  — no TipTap / ProseMirror — so it can render a known URL anywhere:
+  `splitUrl` (host/domain/path split), `truncateUrlLabel` (the
+  middle-ellipsis label), and `faviconUrl` (Google S2 favicon).
+
+### Props (`UrlChipProps`)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `href` | `string` | required | The full, navigable href (`https://…`). |
+| `maxChars` | `number` | `40` | Approximate max chars for the truncated label. The domain is always kept in full; only the path's middle collapses. |
+| `className` | `string` | — | Extra classes merged onto the chip anchor. |
+
+```tsx
+<UrlChip href="https://github.com/wailsapp/wails/blob/main/v3/README.md" />
+// → 🟣 github.com/…/README.md
+```
+
+## `FilePathChip`
+
+Re-exported (with its `FilePathChipProps` type) from the editor's standalone
+path chip,
+[`forms/MarkdownEditor/filePath/FilePathChip.tsx`](../../tools/forms/MarkdownEditor/filePath/FilePathChip.tsx).
+It's already presentational and dependency-light, so this module re-exports it
+rather than duplicating it — `UrlChip` and `FilePathChip` then live behind one
+import.
+
+## Where these are reused
+
+- **Chat markdown bubble.** `UrlChip` is what
+  [`MarkdownMessage`'s `urlChipRule`](../../tools/dev/code/MarkdownMessage/README.md)
+  renders for a bare URL when the host opts in via `ChatConfig.linkChips`.
+- **Composer.** The TipTap composer renders its **own** DOM chip via `ChipNode`
+  (a single inline atom node, `kind: 'url'`), not this React component — but the
+  two are built to match pixel-for-pixel using the same semantic tokens, so a
+  URL reads identically whether it's being typed in the composer or sitting in a
+  rendered bubble.
+
+This shared look is the point: the same URL is one consistent chip across every
+surface.

package/src/chips/UrlChip.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+/**
+ * `<UrlChip>` — a compact, clickable "URL chip" (Chrome-omnibox style):
+ * a favicon + the domain with a middle-ellipsised path
+ * (`github.com/wailsapp/…/README.md`), monospace, with the full href on
+ * hover. Opens in a new tab.
+ *
+ * This is the SURFACE-AGNOSTIC, React counterpart of the TipTap composer's
+ * `editorChip` (`kind: 'url'`, see `forms/MarkdownEditor/chip/ChipNode.ts`).
+ * It matches that chip's look pixel-for-pixel using semantic tokens, so a
+ * URL reads identically whether it sits in the composer (being typed) or in
+ * a rendered chat bubble (`MarkdownMessage`'s `urlChipRule`).
+ *
+ * Presentational + self-contained: it imports only the pure URL detector
+ * helpers (`url/detect`) — no TipTap / ProseMirror — so it can render a
+ * known URL anywhere (chat messages, link lists, etc).
+ *
+ * Favicon degradation: the favicon `<img>` falls back to a lucide `Globe`
+ * glyph on `onError` (offline / blocked / unknown host) so the chip never
+ * shows a broken-image marker — mirroring the composer chip's behaviour.
+ */
+
+import { useState } from 'react';
+import { Globe } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import {
+  splitUrl,
+  truncateUrlLabel,
+  faviconUrl,
+} from '../markdown/url/detect';
+
+export interface UrlChipProps {
+  /** The full, navigable href (`https://…`). */
+  href: string;
+  /**
+   * Approximate max characters for the truncated label. The domain is
+   * always preserved; only the path's middle collapses. Default 40.
+   */
+  maxChars?: number;
+  className?: string;
+}
+
+/**
+ * Render a URL as an inline, clickable chip. Favicon → globe glyph on
+ * favicon load error.
+ */
+export function UrlChip({ href, maxChars = 40, className }: UrlChipProps) {
+  const { host } = splitUrl(href);
+  const favicon = faviconUrl(host);
+  const label = truncateUrlLabel(href, { maxChars });
+
+  // Favicon load failure → swap to the globe glyph. Also covers the empty-
+  // favicon case (unparseable host → faviconUrl returns '').
+  const [imgFailed, setImgFailed] = useState(false);
+  const showGlobe = imgFailed || !favicon;
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={href}
+      className={cn(
+        // Inline pill matching the composer's `editor-chip--url`: muted
+        // surface + border, monospace, semantic tokens only. `max-w` +
+        // `truncate` (on the label) is the CSS safety net under the
+        // precomputed middle-ellipsis label. No raw blue link styling —
+        // the primary accent only lights up the border on hover + the
+        // globe glyph.
+        'inline-flex max-w-[22rem] items-center gap-1 rounded align-baseline',
+        'border border-border bg-muted px-1.5 py-0.5',
+        'font-mono text-[0.8125em] leading-tight text-foreground no-underline',
+        'cursor-pointer transition-colors hover:border-primary',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        className,
+      )}
+    >
+      <span
+        className={cn(
+          'flex size-3.5 shrink-0 items-center justify-center',
+          showGlobe && 'text-primary',
+        )}
+        aria-hidden="true"
+      >
+        {showGlobe ? (
+          <Globe className="size-3.5" />
+        ) : (
+          <img
+            src={favicon}
+            alt=""
+            width={14}
+            height={14}
+            className="size-3.5 rounded-[2px]"
+            onError={() => setImgFailed(true)}
+          />
+        )}
+      </span>
+      <span className="truncate">{label}</span>
+    </a>
+  );
+}
+
+export default UrlChip;

package/src/chips/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Surface-agnostic presentational "chips" — compact inline pills that
+ * render a URL or a file path with a favicon/icon + middle-ellipsis label.
+ *
+ * These match the TipTap composer's `editorChip` look (see
+ * `forms/MarkdownEditor/chip/ChipNode.ts`) but are plain React, so the same
+ * visual is reusable across every surface (composer, chat bubble, lists).
+ *
+ * - `UrlChip`      — clickable URL chip (favicon → globe fallback).
+ * - `FilePathChip` — local file-path chip (re-exported from the editor's
+ *   standalone path chip; it's already presentational/dependency-light, so
+ *   we wrap rather than duplicate).
+ */
+export { UrlChip, default as UrlChipDefault } from './UrlChip';
+export type { UrlChipProps } from './UrlChip';
+
+export {
+  FilePathChip,
+  type FilePathChipProps,
+} from '../markdown/filePath/FilePathChip';