@nanisoft/prism-llms 0.4.0 → 0.5.1

package/dist/md/overview/theming.md

@@ -0,0 +1,89 @@
+# Theming
+
+Packs and modes are two independent axes, delivered as markup attributes with no override path.
+
+Prism themes are complete atmospheres, not a primary-colour swap. A pack changes
+the page ground, the surfaces, the hairlines, the text bases and the focus
+treatment together.
+
+## Two axes
+
+Theming is two independent axes:
+
+- **Pack** selects the palette: `default`, `blush`, `mint`, `lavender`, `sky`
+  or `peach`.
+- **Mode** selects the appearance: `light` or `dark`.
+
+A **theme** is one pack in one mode, such as Blush dark. It is a fully resolved
+token set, not an object and not an API. There is no theme factory.
+
+| Pack | Character |
+| --- | --- |
+| `default` | The neutral base. `primary` reads as ink, not colour. |
+| `blush` | Soft rose, with the softest radius of the set. |
+| `mint` | Soft green, calm and low-energy. |
+| `lavender` | Soft violet, the most saturated brand ramp. |
+| `sky` | Soft blue, the crispest hue and the smallest radius. |
+| `peach` | Soft orange, the warmest hue and the roundest corners. |
+
+## Declarative selection
+
+Put `data-pack` on any element to make it, and its subtree, a theme boundary.
+Add the `dark` class for dark mode. The neutral base pack is the absence of
+`data-pack`, so it is expressed by omitting the attribute.
+
+```tsx
+<!-- the default pack, light -->
+<html lang="en">
+
+<!-- Lavender, dark -->
+<html lang="en" data-pack="lavender" class="dark">
+```
+
+This form is server-rendered and needs no JavaScript. It is also the cheapest
+way to show several packs at once: any subtree can carry its own `data-pack`.
+See the [themes page](/foundation/themes) for all packs side by side.
+
+## Programmatic selection
+
+When a user needs to switch and persist a choice, mount the optional provider
+and read the hook.
+
+```tsx
+import { PrismProvider, usePrismTheme } from '@nanisoft/prism-ui/provider'
+
+function PackPicker() {
+  const { pack, setPack, mode, toggleMode } = usePrismTheme()
+  return (
+    <button onClick={() => setPack('peach')}>
+      {pack} / {mode}
+    </button>
+  )
+}
+
+export function App({ children }: { children: React.ReactNode }) {
+  return <PrismProvider>{children}</PrismProvider>
+}
+```
+
+The provider's only outputs are the two document-element attributes and the
+context. It has no override parameter, no token object and no merge.
+
+## Flash-free first paint
+
+Under a static export there is no server and no middleware, so a blocking inline
+script in `<head>` is what honours a stored choice before first paint. The
+provider's package includes `PrismThemeScript` for exactly this, and the root
+element carries `suppressHydrationWarning` because the script may set the
+attributes before React hydrates.
+
+## There is no consumer theming
+
+Prism does not expose `createPrismTheme`, a per-key merge or semantic overrides.
+The supported path is to select a pack and a mode. A product that needs a
+different palette, a new semantic token or a changed component should request it
+upstream, so every consumer benefits from the change and no project carries a
+private fork.
+
+`className` is for layout composition only. Changing a Prism-owned visual
+property through a class is not supported.

package/dist/md/overview/using-llms.md

@@ -0,0 +1,83 @@
+# Using LLMs
+
+Using LLMs against Prism: the corpus, the Markdown mirror and the read-only MCP endpoint, so an agent reads the same source the human documentation does.
+
+Prism treats agents as first-class consumers. The site, the package declarations,
+the demo sources, the Markdown mirror and the MCP endpoint all project the same
+source, so an agent and a human cannot be told different things.
+
+## Fast path
+
+1. Read `llms.txt` for the catalogue and the page index.
+2. Use `search_docs` when the item name is unknown.
+3. Use `get_item_doc` for the assembled item documentation and its rules.
+4. Use `get_item_props` for the public TypeScript surface.
+5. Use `get_item_source` for the verbatim demo and the public import line.
+6. Use `get_theme_doc` before choosing a pack or reading a token scale.
+7. Use `get_changelog` before upgrading a dependency on Prism.
+
+## The MCP endpoint
+
+The endpoint is public and read-only. It returns Markdown and never writes to a
+consumer project.
+
+```json
+{
+  "mcpServers": {
+    "prism": {
+      "type": "http",
+      "url": "https://prism.nanisoft.com/mcp"
+    }
+  }
+}
+```
+
+## The nine tools
+
+| Tool | Use |
+| --- | --- |
+| `list_items` | Browse the catalogue, filtered by `kind` and `category` |
+| `get_item_doc` | Read the assembled item documentation |
+| `get_item_props` | Read the `## Props` subset of an item |
+| `get_item_source` | Copy the verbatim demo plus the import line |
+| `get_theme_doc` | Read the token contract and the bound scales |
+| `list_pages` | Browse the non-item pages: Overview, Foundation, Content, Changelogs |
+| `get_page` | Read one non-item page as Markdown |
+| `search_docs` | Search the complete corpus and return references |
+| `get_changelog` | Read a published package's changelog, optionally one version |
+
+`list_items` is the one tool that exists because a kind exists; the other seven
+exist because a retrieval pattern exists, and `get_changelog` exists because a
+published breaking change has to be findable by an agent. Search returns
+references, not page bodies, so an agent follows a hit with `get_item_doc` or
+`get_page`.
+
+`get_changelog` takes a package and an optional version, and returns that
+package's own `CHANGELOG.md` as it shipped rather than a summary of it. The
+Changelogs section of this site renders the same bytes, so an agent and a reader
+cannot be told different things about what changed.
+
+## Import contract for generated code
+
+Generated applications import from `@nanisoft/prism-ui`. The internal Base UI
+dependency is not a consumer dependency and must not appear in application
+source.
+
+```tsx
+import { Button } from '@nanisoft/prism-ui/components/button'
+import { Hero01 } from '@nanisoft/prism-ui/blocks/hero-01'
+```
+
+The internal shadcn registry never appears in generated code. It is an integrity
+artifact inside the package, not an install lane.
+
+## Truth rules
+
+- The corpus is versioned with `prism-ui`. Compare the version echoed by
+  `list_items` with the installed package when behaviour looks inconsistent.
+- Demos are single-source files: the same text is rendered live, copied by the
+  site, and returned by `get_item_source`.
+- A generated item has exactly one demo. When an item has no demo, the tool says
+  so rather than fabricating one.
+- Product claims belong to the product team. The corpus documents implementation
+  and usage, never invented customer evidence.

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

@@ -0,0 +1,149 @@
+# AuthPage
+
+A full authentication screen composing a sign-in form with an optional supporting card.
+
+```tsx
+import { AuthPage } from '@nanisoft/prism-ui/pages/auth-page'
+```
+
+## Overview
+
+AuthPage is a complete authentication screen. It composes a sign-in form with an
+optional supporting card, and it owns the centering, the breakpoint and the
+fallback column only. The form carries the credentials, the error slot and the
+submit; the card carries product context beside it.
+
+The page composes these parts:
+
+| Region | Piece | Role |
+| --- | --- | --- |
+| Form | AuthForm01 | the title, the credential fields, the remember row and the submit |
+| Support | Card | an optional surface beside the form for context or reassurance |
+| Footer | footer | a line under the form, such as a legal note or a link |
+
+Every field, label, handler, error and supporting string is a prop. The page
+fetches nothing and imports no router, so the consumer owns the request and the
+links. When no `aside` is passed the layout is one centered column; with one it
+is a two-column split from the large breakpoint up, and the card falls below the
+form on a narrow screen.
+
+## Guidelines
+
+### When to use
+
+Use AuthPage for a sign-in screen whose only task is to collect one email and one
+secret. It works when the screen is the first thing a returning reader sees and
+the supporting card answers a question they are likely to have at that moment.
+
+### When not to use
+
+Do not use it for registration, password reset or profile editing. Those have
+different field sets, and a sign-in card with the wrong fields is a dead end;
+compose a form from the same parts instead.
+
+Do not use it when the screen must carry more than a few words of supporting
+content. The card is context beside a form, not a second page; a longer story
+belongs on a marketing route the reader saw before signing in.
+
+### Best practices
+
+- Set `type`, `autoComplete` and `required` on every field. Browsers use them to
+  fill and validate, so the typing is the whole reason the field is typed.
+- Keep the error to one sentence and mark the failed fields. AuthForm01 sets
+  `aria-invalid` when an error is present, so the form and the message agree.
+- Disable the submit control while a request is in flight and pass `pendingLabel`,
+  so the reader sees that work is happening.
+- Omit `aside` when there is nothing true to say. An empty card is worse than a
+  single centered form.
+- Keep the footer to one line, such as a legal note or a route to create an
+  account, and pass the link in as a node so the consumer owns it.
+
+### Content guidelines
+
+- The title is a short verb phrase in sentence case: "Sign in", "Continue".
+- The description states the outcome, not a policy.
+- An error says what to do next: "Enter your email and password to continue."
+
+**The auth page, with a controlled form and a supporting card.**
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+import { AuthPage } from '@nanisoft/prism-ui/pages/auth-page'
+
+/** The auth page, with a controlled form and a supporting card. */
+export default function AuthPageDemo() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState<string>()
+
+  return (
+    <AuthPage
+      form={{
+        title: 'Sign in',
+        description: 'Welcome back. Enter your details to continue.',
+        error,
+        submitLabel: 'Sign in',
+        fields: [
+          {
+            id: 'auth-page-email',
+            label: 'Email',
+            type: 'email',
+            autoComplete: 'email',
+            placeholder: 'you@example.com',
+            value: email,
+            onChange: setEmail,
+            required: true,
+          },
+          {
+            id: 'auth-page-password',
+            label: 'Password',
+            type: 'password',
+            autoComplete: 'current-password',
+            value: password,
+            onChange: setPassword,
+            required: true,
+          },
+        ],
+        remember: { id: 'auth-page-remember', label: 'Remember me for 30 days' },
+        onSubmit: (event) => {
+          event.preventDefault()
+          setError(
+            email && password ? undefined : 'Enter your email and password to continue.',
+          )
+        },
+      }}
+      aside={{
+        title: 'Everything in one workspace',
+        description: 'Projects, deployments and usage, without a second tool.',
+        children: (
+          <ul className="text-muted-foreground flex flex-col gap-2 text-sm">
+            <li>One place for every team</li>
+            <li>Usage that updates as you deploy</li>
+            <li>Roles from viewer to admin</li>
+          </ul>
+        ),
+      }}
+      footer={<p>No account yet? Create one.</p>}
+    />
+  )
+}
+```
+
+## Props
+
+**`form`** `ComponentProps<typeof AuthForm01>` · required · default: — — The credential form.
+**`aside`** `AuthPageAside` · optional · default: — — A supporting card beside the form. Omit it for a single centered column.
+**`footer`** `ReactNode` · optional · default: — — A node under the form, such as a legal line or a link to another screen.
+
+## Composition
+
+**`exports`** `AuthPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/auth-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `AuthForm01, Card` — the public Prism exports this item composes
+
+## Blocks
+
+- [AuthForm01](https://prism.nanisoft.com/blocks/auth-form-01.md)

package/dist/md/pages/blog-post-page.md

@@ -0,0 +1,136 @@
+# BlogPostPage
+
+A complete blog post screen: title, standfirst, byline with both the display and the machine date, the body at the measure and the trail to the neighbouring posts.
+
+```tsx
+import { BlogPostPage } from '@nanisoft/prism-ui/pages/blog-post-page'
+```
+
+## Overview
+
+BlogPostPage is a complete blog post screen: the title, the standfirst, the
+byline, the body at the reading measure, and the trail to the neighbouring posts.
+
+All four NaniSoft sites publish a blog, each with four posts and the same
+frontmatter: a title, a description, a date and a list of tags. Each one then
+rendered that frontmatter in its own component, with its own wrapper, its own
+measure and its own treatment of the date, and each of them wrote the trail to the
+neighbouring posts separately or not at all.
+
+**The date is two props.** `date` is the words a reader sees and `dateTime` is the
+machine value on the `time` element, and they are kept apart because parsing a
+formatted date back into an ISO one is a guess about a locale. A wrong date in a
+`datetime` attribute is a wrong date in a feed reader and in a search result, and
+neither reader can see the string that was wrong.
+
+## Guidelines
+
+### When to use
+
+Use BlogPostPage as the body of the route that renders one post, handed the
+frontmatter your content pipeline produced.
+
+Use it for every post. A blog whose posts each have their own wrapper is a blog
+whose posts drift apart within a year.
+
+### When not to use
+
+Do not use it for a documentation page. Documentation is a set of short pages
+about one thing; a post is a dated argument about one thing, and a trail to the
+post before it is not a trail through a manual.
+
+Do not use it for a landing page. `MarketingPage` is that composition.
+
+### Best practices
+
+- Pass `dateTime` in `YYYY-MM-DD`. It is the value a feed reader and a search
+  engine order by, and it is the one that is wrong silently.
+- The body is `children`, held by `Prose`. Your pipeline owns the document; this
+  owns the measure and the rhythm. Do not parse it into an array of paragraphs to
+  hand over - that is a second representation of something your pipeline already
+  has.
+- Render only the halves of the trail you have. A previous link on the oldest post
+  is a link to the first post a reader has already read, and a next link on the
+  newest is a promise the site cannot keep.
+- `trailLabel` and `trailLabels` are required alongside a neighbour. They are words
+  a reader reads and hears, and a Page that ships no copy ships no reader-facing
+  copy either: a site that files posts newest-last says the opposite pair.
+- Use `footer` for what comes after the trail: related posts, a newsletter form, a
+  closing call to action. It is a slot because every one of those is a Block, and a
+  Page that took a Block per prop would be a Page whose interface lists the whole
+  catalogue.
+- Pass `indexLink` with the words and the route your archive lives at. The page
+  ships neither.
+
+### Content guidelines
+
+- Write the standfirst as one or two sentences a reader can stop at. It is what an
+  index, a feed and a search result show.
+- Keep tags to nouns. A tag is a category a reader browses, not a sentence.
+- Keep the title to one line at the largest viewport unless the post is the only
+  thing on the page.
+
+**A post: the title, the standfirst, both dates, tags, the body and the trail.**
+
+```tsx
+import { BlogPostPage } from '@nanisoft/prism-ui/pages/blog-post-page'
+
+/** A post: the title, the standfirst, both dates, tags, the body and the trail. */
+export default function BlogPostPageDemo() {
+  return (
+    <BlogPostPage
+      title="Every minute, the whole chain"
+      description="What live full-chain capture at index scale actually takes: the spike, then production, then Kubernetes."
+      date="21 September 2026"
+      dateTime="2026-09-21"
+      author="NaniSoft"
+      readingTime="6 min read"
+      tags={[{ label: 'market-data' }, { label: 'collector' }]}
+      trailLabels={{ previous: 'Previous', next: 'Next' }}
+      trailLabel="More posts"
+      previous={{ title: 'One feed to research them all', href: '#one-feed' }}
+      next={{ title: 'Multi-agent research, mapped', href: '#multi-agent' }}
+      indexLink={{ title: 'All posts', href: '#all' }}
+    >
+      <p>
+        The claim sounds like a feature. It is a measurement with a timestamp on
+        it, and it started as a suspicion that it was impossible.
+      </p>
+      <h2>The assumption that was backwards</h2>
+      <p>
+        Going in, full-chain-per-minute looked like a streaming problem. It was a
+        counting problem, and the count had to fit in a minute.
+      </p>
+      <ul>
+        <li>Every strike, call and put.</li>
+        <li>Open interest, implied volatility and the Greeks.</li>
+        <li>Index futures, index spot and the volatility index.</li>
+      </ul>
+    </BlogPostPage>
+  )
+}
+```
+
+## Props
+
+**`title`** `string` · required · default: — — The post's title. It is the page's `h1`, so the page has exactly one and it is the post's name.
+**`description`** `string` · optional · default: — — The standfirst: one or two sentences under the title that say what the post is about. It is a prop rather than the first paragraph of the body because a reader deciding whether to read needs it before the body starts, and because it is what an index, a feed and a search result show.
+**`date`** `string` · required · default: — — The publication date, already formatted for display, and the machine value for the `time` element's `dateTime`. Both are props, and the machine one is required: `dateTime` is what a reader's browser, a feed reader and a search engine use to order posts, and a formatted string is none of those.
+**`dateTime`** `string` · required · default: — — The date in a machine-readable form, `YYYY-MM-DD`, carried on the `time` element. Required, and deliberately not derived from `date`: parsing a formatted date back into an ISO one is a guess about a locale, and a guess in a `datetime` attribute is a wrong date in a feed.
+**`author`** `ReactNode` · optional · default: — — Who wrote the post. A name, or a link to an author page.
+**`tags`** `readonly BlogPostTag[]` · optional · default: — — The tags on the post, in the order a reader should meet them. Omit them for a post with none: an empty row of badges is a row of nothing.
+**`readingTime`** `string` · optional · default: — — How long the post takes to read, in the consumer's own words.
+**`children`** `ReactNode` · required · default: — — The post's body. Any flow content: paragraphs, headings, lists, code, images, tables. `Prose` holds it to the reading measure and to the block rhythm.
+**`previous`** `BlogPostNeighbour` · optional · default: — — The post before this one and the post after it, for the trail at the foot of the page. Omit the half there is no neighbour for; a "previous" link with no previous post is a link to nothing.
+**`next`** `BlogPostNeighbour` · optional · default: —
+**`trailLabels`** `BlogPostTrailLabels` · required · default: — — The two words the trail renders above the neighbouring posts' titles. Required whenever either neighbour is passed, because they are words a reader reads and a Page that ships no copy ships no reader-facing copy either.
+**`trailLabel`** `string` · required · default: — — The accessible name of the trail between the neighbouring posts. It is required whenever either neighbour is passed, because it is a word a reader hears and a Page that ships no copy ships no reader-facing copy either. "More posts" is the Page's own phrasing and a site that files posts by release calls the same landmark something else.
+**`indexLink`** `BlogPostNeighbour` · optional · default: — — The way back to the archive the post is filed in, rendered as one call to action under the trail. A prop rather than a hardcoded "back to the index", because the words and the route belong to the site that publishes the post and a Page that held either would be a Page making a claim about a consumer's own site.
+**`footer`** `ReactNode` · optional · default: — — A slot for what comes after the trail: a related-posts grid, a newsletter form, a call to action. A slot rather than a prop because every one of those is a Block, and a Page that took a Block per prop would be a Page whose interface lists the whole catalogue.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `BlogPostPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/blog-post-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `Badge, CtaLink, Prose, Section` — the public Prism exports this item composes