@current-docs/embed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dror Ivry
+
+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,30 @@
+# @current-docs/embed
+
+Embeddable Current docs surface for Next.js App Router hosts. It re-exports the Fumadocs layout, page, search, and OpenAPI building blocks behind one stable import, plus `templates/` with the files the docs-embed skill copies into a host app (route group, search route, OpenAPI proxy).
+
+The package ships as TypeScript source, not compiled JS. The host's Next.js build transpiles it, so `transpilePackages: ['@current-docs/embed']` in `next.config.ts` is required. The `fumadocs-*` packages are regular dependencies and come with the install; the host only needs `next`, `react`, and `react-dom` (peer deps).
+
+## Install
+
+```bash
+npm install @current-docs/embed fumadocs-mdx
+```
+
+Inside this monorepo use `"@current-docs/embed": "workspace:*"`; in an onboarded repo use `"@current-docs/embed": "^0.1.0"` from npm.
+
+## Usage
+
+```tsx
+// next.config.ts: transpilePackages: ['@current-docs/embed'], wrap with createMDX()
+// lib/docs-source.ts
+import { createOpenAPI, loader } from '@current-docs/embed';
+import { docs } from '@/.source/server';
+
+export const source = loader({ baseUrl: '/help', source: docs.toFumadocsSource() });
+
+// app/help/layout.tsx
+import { DocsLayout, RootProvider } from '@current-docs/embed';
+// wrap children: <RootProvider><DocsLayout tree={source.getPageTree()}>{children}</DocsLayout></RootProvider>
+```
+
+The full wiring (layout, catch-all page, search and proxy routes, source config) lives in `templates/`; the docs-embed skill copies them in and adjusts paths.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@current-docs/embed",
+  "version": "0.1.0",
+  "description": "Embeddable Current docs surface for Next.js App Router hosts: layout, page, search, and OpenAPI components plus install templates. Published as TypeScript source; consume via transpilePackages.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drorIvry/current-docs.git",
+    "directory": "src/embed"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": "./src/index.tsx",
+    "./api-page": "./src/api-page.tsx",
+    "./templates/*": "./templates/*"
+  },
+  "dependencies": {
+    "fumadocs-core": "^16.10.7",
+    "fumadocs-mdx": "^15.0.13",
+    "fumadocs-openapi": "^11.0.6",
+    "fumadocs-ui": "^16.10.7"
+  },
+  "peerDependencies": {
+    "next": "^16.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^6.0.3",
+    "@types/mdx": "^2.0.13"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit"
+  }
+}

package/src/adaptive.tsx

@@ -0,0 +1,57 @@
+// Adaptive content + action registry primitives for the embedded docs.
+// Claims come from the HOST's own session (auth-inherit); the standalone
+// public site passes no claims, so gated content stays hidden there.
+import type { ReactNode } from 'react';
+
+export interface VisitorClaims {
+  roles: string[];
+}
+
+export interface RoleGateProps {
+  role: string;
+  children: ReactNode;
+}
+
+/** Bind RoleGate to the host session's claims. */
+export function makeRoleGate(claims?: VisitorClaims) {
+  return function RoleGate({ role, children }: RoleGateProps) {
+    if (!claims?.roles.includes(role)) return null;
+    return <>{children}</>;
+  };
+}
+
+/** JSON-schema described action a host app exposes to the docs surface. */
+export interface DocsActionDef {
+  description: string;
+  /** JSON schema for args; validated by the host's action endpoint. */
+  schema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+export type ActionRegistry = Record<string, DocsActionDef>;
+
+/** Minimal required-property validation against the action's JSON schema. */
+export function validateActionArgs(def: DocsActionDef, args: Record<string, unknown>): string | null {
+  const required = (def.schema.required as string[] | undefined) ?? [];
+  for (const key of required) {
+    if (!(key in args)) return `missing required arg: ${key}`;
+  }
+  return null;
+}
+
+/** Serve an action registry as a POST handler ({name, args} -> {result}). */
+export function createActionsHandler(registry: ActionRegistry) {
+  return async function POST(req: Request): Promise<Response> {
+    const body = (await req.json().catch(() => null)) as { name?: string; args?: Record<string, unknown> } | null;
+    const def = body?.name ? registry[body.name] : undefined;
+    if (!def) return Response.json({ error: `unknown action: ${body?.name ?? '(none)'}` }, { status: 404 });
+    const args = body?.args ?? {};
+    const invalid = validateActionArgs(def, args);
+    if (invalid) return Response.json({ error: invalid }, { status: 400 });
+    try {
+      return Response.json({ result: await def.handler(args) });
+    } catch (err) {
+      return Response.json({ error: String(err) }, { status: 500 });
+    }
+  };
+}

package/src/api-page.tsx

@@ -0,0 +1,4 @@
+'use client';
+import { createOpenAPIPage } from 'fumadocs-openapi/ui';
+
+export const OpenAPIPage = createOpenAPIPage();

package/src/docs-action.tsx

@@ -0,0 +1,48 @@
+'use client';
+// A docs-embedded button that invokes a host-registered action. On the public
+// standalone site (no endpoint) it renders as an inert hint instead.
+import { useState } from 'react';
+
+export interface DocsActionProps {
+  name: string;
+  label: string;
+  args?: Record<string, unknown>;
+  /** Host endpoint serving the action registry; absent = standalone site. */
+  endpoint?: string;
+}
+
+export function DocsAction({ name, label, args, endpoint }: DocsActionProps) {
+  const [state, setState] = useState<string>('');
+  if (!endpoint) {
+    return <em data-docs-action={name}>{label} (available inside the app)</em>;
+  }
+  return (
+    <span style={{ display: 'inline-flex', gap: '0.5rem', alignItems: 'center' }}>
+      <button
+        type="button"
+        data-docs-action={name}
+        onClick={async () => {
+          setState('running');
+          const res = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ name, args: args ?? {} }),
+          });
+          const body = (await res.json()) as { result?: unknown; error?: string };
+          setState(res.ok ? `done: ${JSON.stringify(body.result).slice(0, 80)}` : `error: ${body.error}`);
+        }}
+        style={{
+          background: 'var(--cur-primary, #4f46e5)',
+          color: '#fff',
+          border: 'none',
+          borderRadius: 8,
+          padding: '0.4rem 0.8rem',
+          cursor: 'pointer',
+        }}
+      >
+        {label}
+      </button>
+      <code style={{ fontSize: '0.8em' }}>{state}</code>
+    </span>
+  );
+}

package/src/index.tsx

@@ -0,0 +1,56 @@
+// Embeddable docs surface for a host Next.js App Router app.
+// The host mounts docs (browse + search + API reference) as a route group and
+// keeps its own auth: whatever gates the mounting route gates the docs.
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { makeRoleGate, type VisitorClaims } from './adaptive';
+import { DocsAction } from './docs-action';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import type { MDXComponents } from 'mdx/types';
+
+export { RootProvider } from 'fumadocs-ui/provider/next';
+export { DocsLayout } from 'fumadocs-ui/layouts/docs';
+export {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/docs/page';
+export { loader } from 'fumadocs-core/source';
+export { createFromSource } from 'fumadocs-core/search/server';
+export { createOpenAPI } from 'fumadocs-openapi/server';
+
+export { makeRoleGate, createActionsHandler, validateActionArgs } from './adaptive';
+export type { ActionRegistry, DocsActionDef, VisitorClaims } from './adaptive';
+export { DocsAction } from './docs-action';
+
+export interface EmbedMDXOptions {
+  /** Host session claims driving RoleGate visibility (absent = hide gated). */
+  claims?: VisitorClaims;
+  /** Host actions endpoint enabling DocsAction buttons (absent = inert). */
+  actionsEndpoint?: string;
+}
+
+export function getEmbedMDXComponents(
+  components?: MDXComponents,
+  options?: EmbedMDXOptions,
+): MDXComponents {
+  return {
+    ...defaultMdxComponents,
+    Tab,
+    Tabs,
+    Step,
+    Steps,
+    Accordion,
+    Accordions,
+    Card,
+    Cards,
+    RoleGate: makeRoleGate(options?.claims),
+    DocsAction: (props: React.ComponentProps<typeof DocsAction>) => (
+      <DocsAction {...props} endpoint={options?.actionsEndpoint} />
+    ),
+    ...components,
+  };
+}

package/templates/app/api/docs-proxy/route.ts

@@ -0,0 +1,8 @@
+// Copied to <host>/app/api/docs-proxy/route.ts by the docs-embed skill.
+import { openapi } from '@/lib/docs-source';
+
+const proxy = openapi.createProxy({
+  allowedOrigins: ['http://localhost:4001', 'http://localhost:4002'],
+});
+
+export const { GET, POST, PUT, DELETE, PATCH, HEAD } = proxy;

package/templates/app/api/docs-search/route.ts

@@ -0,0 +1,5 @@
+// Copied to <host>/app/api/docs-search/route.ts by the docs-embed skill.
+import { createFromSource } from '@current-docs/embed';
+import { source } from '@/lib/docs-source';
+
+export const { GET } = createFromSource(source);

package/templates/app/help/[[...slug]]/page.tsx

@@ -0,0 +1,41 @@
+// Copied to <host>/app/help/[[...slug]]/page.tsx by the docs-embed skill.
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from '@current-docs/embed';
+import { OpenAPIPage } from '@current-docs/embed/api-page';
+import { notFound } from 'next/navigation';
+import { openapi, source } from '@/lib/docs-source';
+import { getMDXComponents } from '@/mdx-components';
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX
+          components={getMDXComponents({
+            OpenAPIPage: async (props: object) => (
+              <OpenAPIPage {...(await openapi.preloadOpenAPIPage(page))} {...(props as never)} />
+            ),
+          })}
+        />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}

package/templates/app/help/layout.tsx

@@ -0,0 +1,16 @@
+// Copied to <host>/app/help/layout.tsx by the docs-embed skill.
+// Theming: DocsLayout inherits the host's --cur-* CSS variables because the
+// docs render the same @acme/ui components the host renders.
+import { DocsLayout, RootProvider } from '@current-docs/embed';
+import type { ReactNode } from 'react';
+import { source } from '@/lib/docs-source';
+
+export default function HelpLayout({ children }: { children: ReactNode }) {
+  return (
+    <RootProvider theme={{ enabled: false }} search={{ options: { api: '/api/docs-search' } }}>
+      <DocsLayout nav={{ title: 'Help' }} tree={source.getPageTree()}>
+        {children}
+      </DocsLayout>
+    </RootProvider>
+  );
+}

package/templates/lib/docs-source.ts

@@ -0,0 +1,16 @@
+// Copied to <host>/lib/docs-source.ts by the docs-embed skill.
+import { docs } from '@/.source/server';
+import { createOpenAPI, loader } from '@current-docs/embed';
+
+export const source = loader({
+  baseUrl: '/help',
+  source: docs.toFumadocsSource(),
+});
+
+export const openapi = createOpenAPI({
+  input: {
+    'tasks-api': '../../specs/tasks-api.json',
+    'notes-api': '../../specs/notes-api.json',
+  },
+  proxyUrl: '/api/docs-proxy',
+});

package/templates/mdx-components.tsx

@@ -0,0 +1,9 @@
+// Copied into the host app root by the docs-embed skill.
+import { getEmbedMDXComponents } from '@current-docs/embed';
+import type { MDXComponents } from 'mdx/types';
+
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+  return getEmbedMDXComponents(components);
+}
+
+export const useMDXComponents = getMDXComponents;

package/templates/source.config.ts

@@ -0,0 +1,14 @@
+// Copied into the host app root by the docs-embed skill.
+// The host must depend on "@current-docs/embed" (workspace:* inside this monorepo,
+// ^0.1.0 from npm in an onboarded repo) and list it in transpilePackages.
+import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
+
+export const docs = defineDocs({
+  dir: '../../content/docs',
+});
+
+export default defineConfig({
+  mdxOptions: {
+    providerImportSource: '@/mdx-components',
+  },
+});