@terra-symposium/docs 0.1.17 → 0.1.72

package/README.md

@@ -1,10 +1,29 @@
 # Terra Docs
 
-Terra Docs is a reusable React editor and viewer package. Each installation lives in its own host application and controls its own document data, storage, identity, and permissions. This repository contains the component package and installation guide.
+Terra Docs is the shared Terra documentation workspace and Markdown site generator. A repository can use the npm package for an entire Docs site or embed its React editor and viewer in another application.
+
+## Create a repository Docs site
+
+Create a repository from the [Terra Docs starter](https://github.com/Terra-Symposium/docs-template) or install the package in an existing repository:
+
+```sh
+pnpm add -D @terra-symposium/docs
+```
+
+Add Markdown files under `docs/`, then run:
+
+```sh
+pnpm exec terra-docs dev
+pnpm exec terra-docs build
+```
+
+The package creates the routes, navigation, Terra workspace, search index, and 404 page. `docs/index.md` is the home page; nested directories group navigation. `.mdx` files can import interactive examples. Optional `title`, `description`, `hue`, and `sidebar` frontmatter are available when needed. Build output defaults to `docs-dist/`.
+
+Configure a deployment base path with `--base /project-docs/`, and optionally set `--site`, `--title`, and `--description`. Each repository builds its own site; the starter CI checks builds and leaves deployment to the repository owner.
 
 ## Create an instance
 
-Start with the [instance installation guide](src/content/docs/getting-started.md). The React component can be installed into any React 19 app:
+Start with the [instance installation guide](docs/getting-started.md). The React component can be installed into any React 19 app:
 
 ```sh
 pnpm add @terra-symposium/docs
@@ -16,7 +35,7 @@ import type { DocsValue } from '@terra-symposium/docs';
 import '@terra-symposium/docs/style.css';
 ```
 
-The current package release is still under development and is not yet published. To work on a separate local instance against this checkout, install it by local path (`pnpm add /path/to/terra-docs`). Markdown hosts can use `renderMarkdown`, `markdownToDocsValue`, and `docsValueToMarkdown`; remote hosts implement the [storage provider](src/content/docs/storage.md).
+To work on the package itself, clone this repository and run its component playground and Docs site. Markdown hosts can use `renderMarkdown`, `markdownToDocsValue`, and `docsValueToMarkdown`; remote hosts implement the [storage provider](docs/storage.md).
 
 ## Run the playground and docs site
 
@@ -24,9 +43,11 @@ Requirements: Node.js 24.12+, pnpm 10.30.3. Run `pnpm install --frozen-lockfile`
 
 ```sh
 pnpm dev        # Vite component playground
-pnpm docs:dev   # Astro installation and configuration guide
+pnpm docs:dev   # Package-owned Astro site reading this repository's docs/ folder
 ```
 
+The launcher delegates port acquisition to Terra Quality, then starts the dev server with strict port handling. Host apps use this shared launcher; set DOCS_DEV_PORT to override their preferred port.
+
 Build commands: `pnpm run check`, `pnpm run build`, `pnpm run build:demo`, and `pnpm run docs:build`.
 
 The reusable block registry includes accordions, tabs, tables, callouts, code, images, embeds, math, diagrams, raw Markdown, and TypeScript documentation. All are available by default; hosts can disable individual members with the `blocks` prop. Local repository pages stay read-only in the browser.
@@ -68,6 +89,4 @@ const sections: DocsSection[] = [
 </DocsSiteLayout>;
 ```
 
-Repository-backed hosts omit `capabilities`, so the browser shows View and Attachments. Remote hosts pass a `DocsRemoteProvider`, grant `capabilities={{ edit: true, save: true, history: true, publish: true }}`, and wire save, history, and publish callbacks after their own permission checks. These callbacks do not bypass host authorization. Astro hosts can use `@terra-symposium/docs/site-layout.astro` for read-only pages.
-
-For a mutable tree, pass `treeActions` to `DocsSiteLayout`. Its `available(action)` function decides which section, group, and leaf menu items to show; `perform(action)` persists a requested operation through the host. Supported requests include create, rename, duplicate, move or reorder, attachment management, download, and deletion. The host must check permissions again on the server and return an error if the mutation fails. Read-only hosts omit `treeActions` and retain leaf links, Copy link, Open in new tab, and Attachments view.
+`DocsSiteLayout` delegates to the canonical shared workspace and is intended for static React pages. Repository-backed hosts should use `DocsLocalWorkspace`, which loads each leaf and its adjacent attachments from the host-provided tree and remains read-only. Remote hosts should use `TerraDocsWorkspace` with a `DocsHostAdapter`; that adapter supplies the original tree controls and performs create, rename, duplicate, reorder, attachment, export, and delete operations after applying the host's own permission checks.

package/bin/terra-docs.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { watch } from 'node:fs';
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { parse } from 'yaml';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const astroPackage = require.resolve('astro/package.json');
+const astroCli = resolve(dirname(astroPackage), 'bin/astro.mjs');
+const configFile = resolve(packageRoot, 'site/astro.config.mjs');
+const mode = process.argv[2];
+const root = resolve(process.cwd());
+const options = new Map();
+const passthrough = [];
+for (let index = 3; index < process.argv.length; index += 1) {
+	const argument = process.argv[index];
+	if (['--title', '--description', '--site', '--base', '--out', '--port', '--host'].includes(argument)) {
+		const value = process.argv[index + 1];
+		if (!value || value.startsWith('--')) {
+			console.error(`Missing value for ${argument}`);
+			process.exit(2);
+		}
+		options.set(argument, value);
+		index += 1;
+	} else {
+		passthrough.push(argument);
+	}
+}
+
+if (!['dev', 'build', 'preview'].includes(mode)) {
+	console.error('Usage: terra-docs <dev|build|preview> [--title title] [--description text] [--site url] [--base /path/] [--out directory]');
+	process.exit(2);
+}
+
+const docsRoot = resolve(root, 'docs');
+const publicRoot = resolve(root, '.terra-docs/public');
+const publicAssetsRoot = resolve(publicRoot, '_terra-docs/assets');
+const outputDirectory = options.get('--out') ?? 'docs-dist';
+const searchIndexPath = resolve(publicRoot, '_terra-docs/search-index.json');
+const excludedDirectories = new Set(['node_modules', '.astro', 'dist', 'docs-dist']);
+const manifest = await readJson(resolve(root, 'package.json')).catch(() => ({}));
+const siteTitle = options.get('--title') ?? titleFromName(manifest.name) ?? 'Documentation';
+const siteDescription = options.get('--description') ?? manifest.description ?? '';
+const base = normalizeBase(options.get('--base') ?? '/');
+
+async function collectMarkdown(directory, rootDirectory = directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith('.') || (entry.isDirectory() && excludedDirectories.has(entry.name))) continue;
+		const path = join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await collectMarkdown(path, rootDirectory));
+		else if (['.md', '.mdx'].includes(extname(entry.name).toLowerCase())) files.push({ path, relativePath: relative(rootDirectory, path) });
+	}
+	return files;
+}
+
+async function buildSearchIndex() {
+	const files = await collectMarkdown(docsRoot);
+	if (files.length === 0) throw new Error('No Markdown files found in docs/. Add docs/index.md to start a Terra Docs site.');
+	const routeFiles = new Map();
+	const records = [];
+	for (const file of files) {
+		const route = file.relativePath.replace(/\.(?:md|mdx)$/i, '').replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
+		const previous = routeFiles.get(route);
+		if (previous) throw new Error(`Duplicate Docs route "${route || '/'}": docs/${previous} and docs/${file.relativePath}`);
+		routeFiles.set(route, file.relativePath);
+		if (route.toLowerCase() === '404') continue;
+		const source = await readFile(file.path, 'utf8');
+		const { body, frontmatter } = splitFrontmatter(source);
+		const title = frontmatter.title ?? /^#\s+(.+?)\s*#*\s*$/m.exec(body)?.[1]?.trim() ?? titleFromName(file.relativePath.replace(/\.(?:md|mdx)$/i, '').split('/').at(-1));
+		const description = frontmatter.description ?? '';
+		const text = searchableText(body);
+		const hidden = frontmatter.sidebar?.hidden ?? frontmatter.hidden ?? frontmatter.visibility === 'hidden';
+		if (!hidden) records.push({ title, description, href: route ? `${base}${route}/` : base, text });
+	}
+	await copyDocsAssets();
+	await mkdir(dirname(searchIndexPath), { recursive: true });
+	await writeFile(searchIndexPath, `${JSON.stringify(records)}\n`);
+}
+
+async function copyDocsAssets(directory = docsRoot, relativeDirectory = '') {
+	await rm(publicAssetsRoot, { recursive: true, force: true });
+	await copyAssetDirectory(directory, relativeDirectory);
+}
+
+async function copyAssetDirectory(directory, relativeDirectory) {
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (entry.name.startsWith('.') || (entry.isDirectory() && excludedDirectories.has(entry.name))) continue;
+		const source = join(directory, entry.name);
+		const relativePath = relativeDirectory ? join(relativeDirectory, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			await copyAssetDirectory(source, relativePath);
+			continue;
+		}
+		if (['.md', '.mdx'].includes(extname(entry.name).toLowerCase())) continue;
+		const destination = resolve(publicAssetsRoot, relativePath);
+		await mkdir(dirname(destination), { recursive: true });
+		await copyFile(source, destination);
+	}
+}
+
+function splitFrontmatter(source) {
+	const match = /^---\s*\n([\s\S]*?)\n---\s*\n?/.exec(source);
+	if (!match) return { frontmatter: {}, body: source };
+	try {
+		return { frontmatter: parse(match[1]) ?? {}, body: source.slice(match[0].length) };
+	} catch (error) {
+		throw new Error(`Invalid YAML frontmatter: ${error.message}`);
+	}
+}
+
+function searchableText(source) {
+	return source
+		.replace(/^\s*import\s+.+$/gm, ' ')
+		.replace(/^\s*export\s+.+$/gm, ' ')
+		.replace(/```[^\n]*\n?/g, ' ')
+		.replace(/<[^>]*>/g, ' ')
+		.replace(/!??\[([^\]]*)\]\([^)]*\)/g, '$1')
+		.replace(/`([^`]+)`/g, '$1')
+		.replace(/[*_~>#]/g, ' ')
+		.replace(/\s+/g, ' ')
+		.trim();
+}
+
+function normalizeBase(value) {
+	const trimmed = value.trim();
+	if (!trimmed.startsWith('/')) throw new Error('--base must begin with /');
+	return trimmed.endsWith('/') ? trimmed : `${trimmed}/`;
+}
+
+function titleFromName(value = '') {
+	const name = value.replace(/^@[^/]+\//, '').replace(/\.(?:md|mdx)$/i, '').split('/').at(-1) ?? '';
+	return name.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
+}
+
+async function readJson(path) {
+	return JSON.parse(await readFile(path, 'utf8'));
+}
+
+const env = {
+	...process.env,
+	TERRA_DOCS_ROOT: root,
+	TERRA_DOCS_SITE: options.get('--site') ?? '',
+	TERRA_DOCS_BASE: base,
+	TERRA_DOCS_OUT: outputDirectory,
+	PUBLIC_TERRA_DOCS_TITLE: siteTitle,
+	PUBLIC_TERRA_DOCS_DESCRIPTION: siteDescription,
+};
+
+if (mode !== 'preview') await buildSearchIndex();
+
+function runAstro(command) {
+	const args = [astroCli, command, '--root', root, '--config', relative(root, configFile)];
+	if (options.has('--port')) args.push('--port', options.get('--port'));
+	if (options.has('--host')) args.push('--host', options.get('--host'));
+	args.push(...passthrough);
+	const child = spawn(process.execPath, args, { cwd: root, env, stdio: 'inherit' });
+	child.on('error', (error) => {
+		console.error(`Could not start Astro: ${error.message}. Install @terra-symposium/docs in this repository first.`);
+		process.exitCode = 1;
+	});
+	child.on('exit', (code, signal) => {
+		if (signal) process.kill(process.pid, signal);
+		else process.exitCode = code ?? 1;
+	});
+}
+
+runAstro(mode);
+
+if (mode === 'dev') {
+	let timer;
+	try {
+		const watcher = watch(docsRoot, { recursive: true }, () => {
+			clearTimeout(timer);
+			timer = setTimeout(() => buildSearchIndex().catch((error) => console.error(error.message)), 100);
+		});
+		process.on('SIGINT', () => watcher.close());
+		process.on('SIGTERM', () => watcher.close());
+	} catch (error) {
+		console.warn(`Search index updates are disabled: ${error.message}`);
+	}
+}

package/lib-dist/assets/fonts/README.md

@@ -0,0 +1,7 @@
+# Typeface credits
+
+- **Avara Bold and Bold Italic** — designed by Raphaël Bastide, with contributions by Wei Huang, Lucas Le Bihan, Walid Bouchouchi, and Jérémy Landes; released by [Velvetyne Type Foundry](https://velvetyne.fr/fonts/avara/). Licensed under the SIL Open Font License 1.1. See [licenses/OFL-1.1.txt](licenses/OFL-1.1.txt).
+- **AUTHENTIC Sans 90, 130, and 150** — distributed by [AUTHENTIC](https://authentic.website/sans) under the WTFPL.
+- **Inter Variable Roman and Italic** — Copyright (c) 2016 The Inter Project Authors; licensed under the SIL Open Font License 1.1. The files match the Inter font files used by the original Terra Docs host. See [licenses/Inter-OFL-1.1.txt](licenses/Inter-OFL-1.1.txt) and [the Inter project](https://github.com/rsms/inter).
+
+The font files are distributed unchanged from the copies already used by the Terra Symposium website, except Inter is included locally because its original Sanity CSS dependency did not travel with Docs. Their licenses are separate from the Apache-2.0 license for this package.

package/lib-dist/assets/fonts/licenses/Inter-OFL-1.1.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/lib-dist/assets/fonts/licenses/OFL-1.1.txt

@@ -0,0 +1,93 @@
+Copyright 2011-2019 Raphaël Bastide, Wei Huang, Lucas Le Bihan, Walid Bouchouchi, and Jérémy Landes.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/lib-dist/{Docs.d.ts → components/Docs.d.ts}

@@ -17,6 +17,6 @@ export type DocsProps = {
     mode: 'view';
     onChange?: never;
 });
-/** A minimal standalone version of TerraContentEditor's Portable Text surface. */
+/** Controlled editor surface backed by the canonical Terra Docs editor. */
 export declare function Docs(props: DocsProps): JSX.Element;
 //# sourceMappingURL=Docs.d.ts.map

package/lib-dist/components/Docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Docs.d.ts","sourceRoot":"","sources":["../../src/components/Docs.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAEjC,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,iBAAiB,EAAE,CAAC;AAE5C,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GAAG,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAElG,2EAA2E;AAC3E,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,OAAO,CAalD"}

package/lib-dist/components/Docs.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TerraContentEditor } from './terra/editor/TerraContentEditor.js';
+/** Controlled editor surface backed by the canonical Terra Docs editor. */
+export function Docs(props) {
+    return (_jsx("div", { className: ['terra-docs', props.className].filter(Boolean).join(' '), children: _jsx(TerraContentEditor, { content: props.value, readOnly: props.mode === 'view', ...(props.blocks !== undefined ? { blocks: props.blocks } : {}), ...(props.mode === 'edit'
+                ? { onChange: (value) => props.onChange(value) }
+                : {}) }) }));
+}
+//# sourceMappingURL=Docs.js.map

package/lib-dist/components/Docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Docs.js","sourceRoot":"","sources":["../../src/components/Docs.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAkB1E,2EAA2E;AAC3E,MAAM,UAAU,IAAI,CAAC,KAAgB;IACnC,OAAO,CACL,cAAK,SAAS,EAAE,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YACvE,KAAC,kBAAkB,IACjB,OAAO,EAAE,KAAK,CAAC,KAAK,EACpB,QAAQ,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,KAC3B,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAC5D,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM;gBACxB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAgB,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAkB,CAAC,EAAE;gBACxE,CAAC,CAAC,EAAE,CAAC,GACP,GACE,CACP,CAAC;AACJ,CAAC"}

package/lib-dist/{LocalDocsWorkspace.d.ts → components/LocalDocsWorkspace.d.ts}

@@ -1,5 +1,6 @@
-import type { DocsHostAttachment, DocsHostTreeNode, DocsCustomBlock } from './host.js';
-import type { JSX } from 'react';
+import type { DocsBlockOptions } from './blocks.js';
+import type { DocsHostAttachment, DocsHostTreeNode, DocsCustomBlock } from '../lib/host.js';
+import type { JSX, ReactNode } from 'react';
 /** A local page supplied by a repository or static site build. */
 export type DocsLocalPage = {
     id: string;
@@ -18,10 +19,16 @@ export type DocsLocalWorkspaceProps = {
     pathname: string;
     title: string;
     description?: string;
+    /** Optional host-owned content rendered before the page body in View mode. */
+    beforeContent?: ReactNode;
+    hue?: number | null;
     rootPath?: string;
     homePath?: string;
+    afterContent?: ReactNode;
     customBlocks?: DocsCustomBlock[];
+    blocks?: DocsBlockOptions;
 };
+export declare function findDocsLocalPage(pages: DocsLocalPage[], value: unknown): DocsLocalPage | undefined;
 /**
  * Render repository-owned Markdown with the original Terra Docs workspace.
  * This adapter has no write operations, account dependency, or server requirement.

package/lib-dist/components/LocalDocsWorkspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalDocsWorkspace.d.ts","sourceRoot":"","sources":["../../src/components/LocalDocsWorkspace.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAIV,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5C,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAqBF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,OAAO,GACb,aAAa,GAAG,SAAS,CAwB3B;AAsCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,GAAG,CAAC,OAAO,CAiK9E"}