@nanisoft/prism-llms 0.3.0 → 0.5.0

package/dist/md/pages/not-found-page.md

@@ -0,0 +1,105 @@
+# NotFoundPage
+
+A complete not-found screen: the status code as the heading of the page, one sentence about what happened, and the ways out.
+
+```tsx
+import { NotFoundPage } from '@nanisoft/prism-ui/pages/not-found-page'
+```
+
+## Overview
+
+NotFoundPage is a complete not-found screen: the code, what happened, and the ways
+out.
+
+All four NaniSoft sites compose one, each in its own not-found route, and three of
+them are the same six lines with a different product name on it: a display title
+carrying the code, one muted sentence, and two or three links. The fourth wrote
+the same thing in its own markup. Four hand-written screens for one shape.
+
+It is a Page rather than a Block because it is a whole screen: it owns the
+document's `h1`, it is what a router renders when a route does not resolve, and
+the band's job is not separable from the screen's. There is one correct page here
+and it is short.
+
+## Guidelines
+
+### When to use
+
+Use NotFoundPage as the body of whatever route your framework names for a
+not-found response: Next's `not-found.tsx`, a Nuxt error page, a route your own
+router falls through to.
+
+Use it for every status that means "this address is not a page here", not only
+404. A 410 and a 404 are the same screen with a different code, and the code is a
+prop.
+
+### When not to use
+
+Do not use it for a request that failed. That is an error page with a retry, and a
+reader who sees "this page does not exist" when the page exists and did not load
+will not believe you next time.
+
+Do not use it for a permission failure the reader might be granted later. That is
+a 403, and it needs a sign-in link rather than a way back to the landing.
+
+### Best practices
+
+- **The code is the `h1` and the sentence is not.** A not-found page whose `h1` is
+  "Page not found" gives a search engine and a screen reader nothing distinct to
+  index, and the code is the one string on the page that is the same for every
+  broken URL. The code takes the display step and the sentence takes the muted one,
+  which is the reverse of what a reader sees first and the right way round for
+  anything that reads the outline.
+- Put the most useful destination first, and weight it as the primary action. A
+  not-found page that offers the homepage link before the documentation sends a
+  reader further from what they wanted.
+- Leave `newTab` off every link. A reader who followed a broken link and is sent
+  to a new tab has to find their way back.
+- Use the `children` slot for a search box or a list of recent posts, which is
+  what turns a dead end into a page.
+
+### Content guidelines
+
+- Write the sentence as a fact about the address, not as an apology. "No node
+  here" beats "Sorry, we could not find that page".
+- Say whether the page might exist later if it does. "This page does not exist
+  (yet)" is one clause longer and saves a support ticket.
+- Keep each link label to one or two words.
+
+**The not-found screen: the code as the h1, one sentence, and the ways out.**
+
+```tsx
+import { NotFoundPage } from '@nanisoft/prism-ui/pages/not-found-page'
+
+/** The not-found screen: the code as the h1, one sentence, and the ways out. */
+export default function NotFoundPageDemo() {
+  return (
+    <NotFoundPage
+      code="404"
+      title="No node here."
+      description="The estate is fully mapped. This URL is not in the graph."
+      linksLabel="Ways out"
+      links={[
+        { label: 'Read the docs', href: '#docs' },
+        { label: 'Back to the landing', href: '#landing' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`code`** `string` · required · default: — — The status code, shown as the page's own `h1`. Required, and a string rather than a number because it is displayed, not computed: a Page never decides what code it is answering.
+**`title`** `string` · required · default: — — The headline under the code: the sentence that says what happened. It is the part a reader actually reads, and it is the caller's because every product says it differently - "No node here", "This page does not exist (yet)".
+**`description`** `string` · optional · default: — — One or two sentences under the headline, for anything a reader should know before they follow one of the links: that the URL may be mistyped, that the page is planned, that a search would find it.
+**`links`** `readonly NotFoundLink[]` · required · default: — — The ways out, in the order a reader should see them. Put the destination most likely to help first; a not-found page that offers a homepage link before the documentation sends a reader further from what they wanted.
+**`linksLabel`** `string` · required · default: — — The accessible name of the row of ways out. It is required, because it is a word a reader hears and a Page that ships no copy ships no reader-facing copy either. "Ways out" is the Page's own phrasing; a site that files its destinations differently names the same landmark differently.
+**`children`** `ReactNode` · optional · default: — — A slot for whatever else the site wants to say here: a search box, a list of recent posts, a contact address.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `NotFoundPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/not-found-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `CtaLink, Prose, Section` — the public Prism exports this item composes

package/dist/md/pages/settings-page.md

@@ -0,0 +1,206 @@
+# SettingsPage
+
+A full settings screen composing the app shell, a page header and tabs of grouped settings forms.
+
+```tsx
+import { SettingsPage } from '@nanisoft/prism-ui/pages/settings-page'
+```
+
+## Overview
+
+SettingsPage is a complete settings screen. It composes the shell, a page header
+and a set of tabs, where each tab is either a saved settings form or a read-only
+panel. The page owns the sequence and the tab wiring only.
+
+The page composes these parts:
+
+| Region | Piece | Role |
+| --- | --- | --- |
+| Frame | AppShell01 | the navigation rail, the top bar and the mobile navigation sheet |
+| Header | PageHeader01 | the trail, the screen title and its actions |
+| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | the peer settings groups |
+| Forms | SettingsPanel01 | the grouped and saved form for one tab |
+
+A tab that carries `panel` renders `SettingsPanel01`: a titled card with grouped
+sections, a save footer and one submit. A tab that carries `content` renders the
+node as-is, which suits a read-only summary or a view that is not a form. Sections,
+fields, options and labels are all props, and the page fetches nothing.
+
+## Guidelines
+
+### When to use
+
+Use SettingsPage when a screen changes several settings that group naturally, and
+each group can be saved on its own. It works when the tabs are stable and a reader
+returns to one group rather than scanning the whole screen.
+
+### When not to use
+
+Do not use it for a single setting. One field behind a tab is a heavier frame
+than the choice deserves; put the control on the screen that owns it.
+
+Do not use it when the settings must be compared side by side. Tabs hide one
+group to show another, so a choice that depends on another group's value belongs
+on one page, not behind a tab.
+
+### Best practices
+
+- Keep one save per panel. A mixed model, where some fields save and others apply
+  immediately, makes the footer's promise unclear.
+- Give every field a stable `id`, so the label is linked to the control.
+- Use `content` for a read-only group. A panel with no `submitLabel` renders no
+  footer, which is the honest shape for a view that does not save.
+- Set `defaultValue` to the group a reader is most likely to want, rather than
+  relying on the first tab by luck.
+- Pass the same navigation node to both the rail and the sheet, and keep its ids
+  unique because AppShell01 renders it twice.
+
+### Content guidelines
+
+- A tab label is one word in sentence case: "General", "Notifications".
+- A section title is one or two words and a field label is a short noun phrase.
+- A description states the effect of the group, not a policy for it.
+
+**The settings page, with a grouped form per tab.**
+
+```tsx
+'use client'
+
+import { SettingsPage } from '@nanisoft/prism-ui/pages/settings-page'
+
+const LINKS = [
+  { href: '#general', label: 'General', current: false },
+  { href: '#settings', label: 'Settings', current: true },
+  { href: '#members', label: 'Members', current: false },
+]
+
+/** The settings page, with a grouped form per tab. */
+export default function SettingsPageDemo() {
+  return (
+    <SettingsPage
+      shell={{
+        navigationLabel: 'Primary',
+        brand: <span className="text-sm font-semibold">Northwind</span>,
+        breadcrumbs: [{ label: 'Settings', href: '#settings' }, { label: 'Workspace' }],
+        navigation: (
+          <ul className="flex flex-col gap-1 text-sm">
+            {LINKS.map((link) => (
+              <li key={link.href}>
+                <a
+                  href={link.href}
+                  className={
+                    link.current
+                      ? 'bg-accent text-accent-foreground block rounded-md px-3 py-2 font-medium'
+                      : 'text-muted-foreground hover:text-foreground block rounded-md px-3 py-2'
+                  }
+                >
+                  {link.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ),
+      }}
+      header={{
+        title: 'Workspace settings',
+        description: 'Manage how this workspace behaves for everyone on the team.',
+      }}
+      tabs={[
+        {
+          value: 'general',
+          label: 'General',
+          panel: {
+            title: 'General',
+            description: 'Shown to everyone you collaborate with.',
+            submitLabel: 'Save changes',
+            secondaryAction: { label: 'Cancel' },
+            sections: [
+              {
+                id: 'identity',
+                title: 'Identity',
+                fields: [
+                  {
+                    kind: 'text',
+                    id: 'settings-workspace-name',
+                    label: 'Workspace name',
+                    defaultValue: 'Northwind',
+                  },
+                  {
+                    kind: 'textarea',
+                    id: 'settings-workspace-description',
+                    label: 'Description',
+                    placeholder: 'What does this workspace do?',
+                    rows: 3,
+                  },
+                  {
+                    kind: 'select',
+                    id: 'settings-workspace-region',
+                    label: 'Data region',
+                    placeholder: 'Choose a region',
+                    defaultValue: 'eu-west',
+                    options: [
+                      { label: 'Europe West', value: 'eu-west' },
+                      { label: 'US East', value: 'us-east' },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        },
+        {
+          value: 'notifications',
+          label: 'Notifications',
+          panel: {
+            title: 'Notifications',
+            description: 'Choose what the workspace sends and when.',
+            submitLabel: 'Save changes',
+            sections: [
+              {
+                id: 'email',
+                title: 'Email',
+                fields: [
+                  {
+                    kind: 'switch',
+                    id: 'settings-weekly-digest',
+                    label: 'Weekly digest',
+                    description: 'A summary of activity every Monday.',
+                    defaultChecked: true,
+                  },
+                  {
+                    kind: 'switch',
+                    id: 'settings-mention-alerts',
+                    label: 'Mention alerts',
+                    description: 'Notify me when someone mentions my name.',
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`shell`** `Omit<ComponentProps<typeof AppShell01>, 'children'>` · required · default: — — The frame: rail, top bar and mobile navigation sheet.
+**`header`** `ComponentProps<typeof PageHeader01>` · required · default: — — The page title band.
+**`tabs`** `SettingsPageTab[]` · required · default: — — The tabs, in order. At least one is required.
+**`defaultValue`** `string` · optional · default: — — The tab shown first, for uncontrolled tabs. Defaults to the first tab.
+**`value`** `string` · optional · default: — — The controlled active tab.
+**`onValueChange`** `(value: string) => void` · optional · default: —
+
+## Composition
+
+**`exports`** `SettingsPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/settings-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `AppShell01, PageHeader01, SettingsPanel01, Tabs` — the public Prism exports this item composes
+
+## Blocks
+
+- [AppShell01](https://prism.nanisoft.com/blocks/app-shell-01.md)
+- [PageHeader01](https://prism.nanisoft.com/blocks/page-header-01.md)
+- [SettingsPanel01](https://prism.nanisoft.com/blocks/settings-panel-01.md)

package/dist/prism-skill.md

@@ -0,0 +1,50 @@
+# Prism agent skill
+
+Prism is NaniSoft's design system: design tokens, a React component library, a
+documentation site, and this agent surface. This is the fast path. The index is
+[`/llms.txt`](https://prism.nanisoft.com/llms.txt) and every page in full is
+[`/llms-full.txt`](https://prism.nanisoft.com/llms-full.txt); both are generated from the
+checked catalogue and the authored pages.
+
+## Start here
+
+```tsx
+import '@nanisoft/prism-ui/styles.css'
+
+import { PrismProvider, PrismThemeScript } from '@nanisoft/prism-ui/provider'
+```
+
+Import the one stylesheet once. The provider is optional: the declarative axes
+are `data-pack` on `<html>` and the `dark` class for mode.
+
+## Import contract
+
+- Components: `@nanisoft/prism-ui/components/<slug>`
+- Blocks: `@nanisoft/prism-ui/blocks/<slug>`
+- Pages: `@nanisoft/prism-ui/pages/<slug>`
+
+Compound parts stay inside their module. Base UI and every internal path are
+never a consumer import.
+
+## MCP
+
+The read-only MCP endpoint is `https://prism.nanisoft.com/mcp`. It exposes nine tools:
+`list_items`, `get_item_doc`, `get_item_props`, `get_item_source`,
+`get_theme_doc`, `list_pages`, `get_page`, `search_docs` and
+`get_changelog`.
+
+## Truth rules
+
+- Prism is the one source of truth. A consumer composes; it never writes CSS and
+  never overrides a style.
+- There is no override path. When Prism lacks a component, token or variant,
+  request it upstream.
+- Generated code imports from `@nanisoft/prism-ui` only.
+
+## This corpus
+
+Generated from the catalogue and the authored pages: 34
+Components, 19 Blocks and 6 Pages, plus the Overview,
+Foundation, Content and Changelogs pages. The Changelogs pages are each
+published package's own changelog, byte for byte; `get_changelog` returns one
+package's, optionally one version of it.

package/dist/store.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The `PrismDocsStore` contract: the one type the MCP server validates at
+ * runtime, and the one runtime guard that produces it.
+ *
+ * Ticket 12 section 7 makes this file the canonical home. The store is a
+ * build-time projection of the catalogue, the authored pages and the token
+ * cascade; the MCP server imports both the type and `parsePrismDocsStore` and
+ * never redeclares either.
+ *
+ * `kind` is ticket 09's closed union. The JSON arrives as `unknown`, the guard
+ * narrows it structurally, and `kind` is validated through a local list that is
+ * tied to the catalogue's type with `satisfies` plus a type-equality assertion.
+ * A widened `kind: string` is rejected at runtime and at compile time, which is
+ * the bug the old package recorded.
+ */
+import type { CatalogKind, ComponentCategory } from '@nanisoft/prism-ui/catalog';
+export declare const STORE_KINDS: readonly ["component", "block", "page"];
+export declare const STORE_CATEGORIES: readonly ["Call to action", "Forms and inputs", "Feedback", "Layout", "Data display", "Typography", "Miscellaneous"];
+export declare const STORE_STATUSES: readonly ["stable", "deprecated"];
+/**
+ * The content Sections, in the reading order the site publishes them, and the
+ * same order `llms.txt` groups them in.
+ *
+ * These are the Section *directories*, so the list is the walk the corpus builder
+ * takes and the set of directories the site's gate checks. The three catalogue
+ * Sections are not here: an Item is a catalogue entry with a `kind`, and its page
+ * is emitted from the Catalogue rather than walked out of the content tree, so
+ * adding `components` to this list would make the walk look for a directory that
+ * is not one.
+ *
+ * **A Section's route is its directory, and the two were renames.** `docs` is
+ * `overview` and `foundations` is `foundation`, which is the rule that a prose
+ * Section is one body of knowledge and takes a singular route while a catalogue
+ * Section is a collection of many Items and takes a plural one. An agent holding
+ * a cached `llms.txt` from before the move still resolves every URL it names,
+ * because the site Worker redirects each of these routes permanently, and the
+ * corpus is rebuilt per release and points at the new ones. Nothing here is
+ * aliased: a page's `section` is the directory it is filed in, which is what
+ * `get_page` matches on, and a `Record<StoreSection, string>` over a list that
+ * had to be edited in the same commit as the rename is a second list that can be
+ * half done.
+ */
+export declare const STORE_SECTIONS: readonly ["overview", "foundation", "content", "changelogs"];
+/**
+ * The label each content Section is read under, in every artifact that groups
+ * pages by Section.
+ *
+ * `Record<StoreSection, string>` rather than a separate list, because a Section
+ * added to `STORE_SECTIONS` with no label is a compile error here rather than a
+ * Section that `llms.txt`, `list_pages` and the Corpus each spell their own way.
+ * The keys are the Section directories themselves, so the label cannot be filed
+ * under a Section that does not exist.
+ *
+ * The label is the Section's name rather than its directory, which is the whole
+ * point of the pair: the directory is what the tree is called, and the name is
+ * what a reader and an agent are told. `llms.txt` groups under these headings and
+ * `list_pages` counts them, so a Section renamed without its label renamed here
+ * would be advertised under two names in two artifacts.
+ */
+export declare const STORE_SECTION_TITLES: Record<StoreSection, string>;
+export declare const STORE_PACKS: readonly ["default", "blush", "mint", "lavender", "sky", "peach"];
+export declare const STORE_MODES: readonly ["light", "dark"];
+export declare const STORE_SCALE_GROUPS: readonly ["motion", "typography", "spacing", "shadow", "breakpoint", "container"];
+export type StoreKind = (typeof STORE_KINDS)[number];
+export type StoreStatus = (typeof STORE_STATUSES)[number];
+export type StoreSection = (typeof STORE_SECTIONS)[number];
+export type PackId = (typeof STORE_PACKS)[number];
+export type Mode = (typeof STORE_MODES)[number];
+export type PrismScaleGroup = (typeof STORE_SCALE_GROUPS)[number];
+/** `'doc'` is a non-item page (a guide, a Foundation, a Content page). */
+export type TokenGroup = 'semantic' | PrismScaleGroup;
+export interface PrismDocsExample {
+    readonly title: string;
+    readonly code: string;
+}
+export interface PrismDocsStoreEntry {
+    readonly id: string;
+    readonly slug: string;
+    readonly kind: CatalogKind;
+    readonly name: string;
+    readonly category: ComponentCategory | null;
+    readonly status: StoreStatus;
+    readonly description: string;
+    /** The item's canonical site path, for example `/components/button`. */
+    readonly url: string;
+    /** The canonical path plus `.md`, for example `/components/button.md`. */
+    readonly mirror: string;
+    readonly source: string;
+    readonly exports: readonly string[];
+    /** The public import line ticket 11 section 9 fixes. */
+    readonly importLine: string;
+    /** The full per-item spec, byte-identical to the mirror file. */
+    readonly doc: string;
+    /** The `## Props` section body, for a Component. */
+    readonly props?: string;
+    /** The `## Composition` section body, for a Block or a Page. */
+    readonly composition?: string;
+    /** The verbatim demo plus its title, when a demo exists. */
+    readonly example?: PrismDocsExample;
+    readonly references: {
+        readonly blocks: readonly string[];
+        readonly pages: readonly string[];
+    };
+}
+export interface PrismDocsPage {
+    readonly id: string;
+    /** The page's path below its Section, without the extension: `tokens/colors`. */
+    readonly slug: string;
+    /** The top-level Section directory the page sits in. */
+    readonly section: StoreSection;
+    readonly title: string;
+    readonly description: string;
+    /** The page's canonical site path, for example `/overview/quickstart`. */
+    readonly url: string;
+    readonly markdown: string;
+    readonly mirror: string;
+}
+/**
+ * One version entry of a published package's changelog.
+ *
+ * `body` is the text under the version's own `## <version>` heading, sliced by
+ * the shared changelog rule and never re-levelled: the file is published whole
+ * and re-levelling a heading would be another transformation between the
+ * package's bytes and the agent's.
+ */
+export interface PrismChangelogRelease {
+    readonly version: string;
+    readonly body: string;
+}
+/**
+ * One published package's changelog, projected from the generated file the site
+ * renders.
+ *
+ * This is the field the ninth read-only tool answers from, and it exists so that
+ * a breaking change in a published package is discoverable by an agent. The
+ * reference design system shipped a breaking module-system change that no agent
+ * using it could find, because its corpus had no changelog field and no tool
+ * could return one.
+ *
+ * `text` is the generated file verbatim, which is a byte-for-byte copy of the
+ * package's own `CHANGELOG.md`. `releases` is the shared rule's reading of those
+ * same bytes, and the two cannot disagree because the rule is the only thing
+ * that produces either.
+ */
+export interface PrismChangelog {
+    /** The published npm name, which is what an agent asks for. */
+    readonly package: string;
+    /** The route segment the changelog is published at: the unscoped name. */
+    readonly slug: string;
+    /** The site's route for it, and the mirror an agent can fetch instead. */
+    readonly route: string;
+    /** The file's own first heading, which names the package. */
+    readonly title: string;
+    /** Every version the file records, newest first as the generator writes it. */
+    readonly versions: readonly string[];
+    readonly releases: readonly PrismChangelogRelease[];
+    /** The generated file, byte for byte. */
+    readonly text: string;
+}
+export interface PrismSemanticToken {
+    readonly token: string;
+    readonly value: string;
+}
+export interface PrismScaleToken {
+    readonly token: string;
+    readonly value: string;
+    /** The Tailwind binding, when the token has a mirror custom property. */
+    readonly binding?: string;
+}
+export interface PrismThemeTokens {
+    readonly pack: PackId;
+    readonly mode: Mode;
+    readonly semantic: readonly PrismSemanticToken[];
+}
+export interface PrismTokensProjection {
+    readonly packs: readonly PackId[];
+    readonly modes: readonly Mode[];
+    readonly themes: readonly PrismThemeTokens[];
+    readonly scales: Record<PrismScaleGroup, readonly PrismScaleToken[]>;
+}
+export interface PrismDocsStore {
+    readonly version: string;
+    readonly items: readonly PrismDocsStoreEntry[];
+    readonly pages: readonly PrismDocsPage[];
+    /**
+     * One entry per published package that ships a changelog. Required rather than
+     * optional: the field is what makes a published breaking change discoverable
+     * by an agent, and a store that quietly omitted it would leave the tool that
+     * reads it answering for nothing while every other gate stayed green.
+     */
+    readonly changelogs: readonly PrismChangelog[];
+    readonly tokens: PrismTokensProjection;
+}
+/**
+ * Narrow an `unknown` JSON payload to a `PrismDocsStore`, or throw with the
+ * offending path. This is the only place a `PrismDocsStore` is produced from
+ * JSON: nothing is assigned with `as`, and `kind` is never widened to `string`.
+ *
+ * The order of the fields is the order of the layers that have to have carried
+ * the change. `items` before `changelogs`, so a document with a widened `kind`
+ * reports the path a reader is more likely to be looking at.
+ */
+export declare function parsePrismDocsStore(raw: unknown): PrismDocsStore;