@openpresentation/opf 0.2.1 → 0.3.0

package/README.md

@@ -2,9 +2,9 @@
 
 Canonical Open Presentation Format package for JavaScript and TypeScript.
 
-Publishes the OPF schemas, catalog presets, raw spec files, generated TypeScript types, and local validation helpers. The schema is pre-stable (0.x — expect breaking changes between minor versions until 1.0). This package does not render PowerPoint files, parse `.pptx`, fetch remote catalogs, or use AI.
+Publishes the OPF schemas, catalog presets, raw spec files, generated TypeScript types, examples, docs, and local validation helpers. The schema is pre-stable (0.x — expect breaking changes between minor versions until 1.0). This package does not render PowerPoint files, parse `.pptx`, fetch remote catalogs, call hosted APIs, provide telemetry, or use AI.
 
-The canonical npm package remains `@openpresentation/opf`; a separate `@openpresentation/opf-spec` package is not used for v0.2.0 so existing downstream imports stay stable. The packed npm artifact includes package-addressable OPF schemas, catalogs, reference files, and `openapi.yaml` under `spec/`.
+The canonical npm package remains `@openpresentation/opf`; a separate `@openpresentation/opf-spec` package is not used for v0.2.0 so existing downstream imports stay stable. The packed npm artifact includes package-addressable OPF schemas, catalogs, reference files, and an optional downstream-service reference `openapi.yaml` under `spec/`.
 
 Repository: https://github.com/OpenPresentation/opf
 
@@ -93,6 +93,75 @@ export function LayoutThumbnail({ slug }: { slug: string }) {
 Raw HTML source-of-truth lives under `spec/previews/layouts/<slug>.html` and is
 also addressable via `@openpresentation/opf/spec/previews/layouts/<slug>.html`.
 
+### Example decks
+
+`@openpresentation/opf/examples` ships every `.opf.json` file from `examples/`
+in the upstream repo, already parsed and validated against the presentation
+schema at build time.
+
+```ts
+import {
+  examples,
+  galleries,
+  getExample,
+  getExamplesByGallery,
+} from "@openpresentation/opf/examples";
+
+const compliance = getExample("compliance-readiness-review");
+const businessDecks = getExamplesByGallery("business-functions");
+
+console.log(`${examples.length} example decks across ${galleries.length} galleries`);
+```
+
+Each `ExampleRecord` includes the parsed `Presentation` object plus its
+repo-relative path, top-level category (`gallery`, `technical`, …), and
+gallery slug when applicable.
+
+### Documentation pages
+
+`@openpresentation/opf/docs` ships the top-level `docs/*.md` reference pages
+(`schema-reference`, `catalog-schema-reference`, `content-payloads`,
+`content-item-design-overrides`, `examples`). Subdirectories like
+`docs/migrations` and `docs/plans` are intentionally excluded — those move too
+quickly to ship inside a pinned npm release.
+
+```ts
+import { docs, getDoc } from "@openpresentation/opf/docs";
+
+for (const doc of docs) {
+  console.log(`${doc.title} — ${doc.file}`);
+}
+
+const schemaRef = getDoc("schema-reference");
+console.log(schemaRef?.markdown.slice(0, 200));
+```
+
+### Upstream README
+
+`@openpresentation/opf/repo-readme` exposes the raw markdown of the upstream
+`OpenPresentation/opf` README.md at the version pinned by this release. Use it
+when you want to mirror the canonical README inside another site or app
+without doing a network fetch.
+
+```ts
+import { repoReadme } from "@openpresentation/opf/repo-readme";
+
+console.log(repoReadme.split("\n").slice(0, 3).join("\n"));
+```
+
+Validation results carry `errors` (structural problems that make `valid`
+false) and `warnings` (advisory issues such as unknown catalog ids in
+`narrative`, `design`, or chart `type` references — these never affect
+`valid`). Documents that declare matching inline `catalogs.<kind>.records[]`
+or a custom `catalogs.<kind>.source` are exempt from unknown-id warnings for
+that kind.
+
+```ts
+const result = validatePresentation(deck);
+if (!result.valid) console.error(result.errors);
+for (const warning of result.warnings) console.warn(warning.path, warning.message);
+```
+
 Validate catalog records locally:
 
 ```ts
@@ -114,7 +183,7 @@ import presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.js
 };
 ```
 
-The raw spec manifest exposes typed package paths for files that should be resolved from npm instead of GitHub:
+The raw spec manifest exposes typed package paths for files that should be resolved from npm instead of GitHub. `openapi.yaml` is a reference contract for downstream services that choose to expose OPF over HTTP; OpenPresentation does not host that API.
 
 ```ts
 import { specFileEntries } from "@openpresentation/opf/spec-files";

package/dist/catalogs.d.ts

@@ -34,7 +34,7 @@ declare const audiences: readonly [{
     readonly technicalFluency: "high";
     readonly decisionPower: "advisory";
     readonly attentionBudgetMinutes: 45;
-    readonly recommendedNarratives: readonly ["engineering-update", "challenge-resolution", "innovation", "weekly-progress"];
+    readonly recommendedNarratives: readonly ["status-update", "challenge-resolution", "innovation", "weekly-progress"];
     readonly recommendedTones: readonly ["technical", "casual", "conversational"];
     readonly tags: readonly ["internal", "engineering", "practitioner"];
 }, {
@@ -249,7 +249,7 @@ declare const tones: readonly [{
     readonly voiceCues: readonly ["Use first and second person.", "Use contractions ('we're', 'it's', 'don't').", "Favor short sentences and active voice.", "Frame metrics with a human-scale anchor when possible."];
     readonly avoid: readonly ["Stiff corporate jargon.", "Long compound sentences.", "Overuse of superlatives.", "Bureaucratic passive voice."];
     readonly samplePhrases: readonly ["We shipped the new dashboard last week, and customers are already moving over.", "Here's where we ended up on hiring this quarter.", "It's been a busy month — here's the recap."];
-    readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "all-hands"];
+    readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "focus"];
     readonly tags: readonly ["internal", "warm", "conversational"];
 }, {
     readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -271,7 +271,7 @@ declare const tones: readonly [{
     readonly voiceCues: readonly ["State the claim, then the mechanism, then the evidence.", "Use exact terminology — don't soften technical terms for general readability.", "Quote benchmarks with conditions (cold/warm, p50/p95/p99, dataset, hardware).", "Prefer diagrams and tables over prose paragraphs for structural information."];
     readonly avoid: readonly ["Vague claims ('much faster', 'better', 'easier').", "Marketing framing without supporting data.", "Glossing over caveats and tradeoffs.", "Casual register that obscures precision."];
     readonly samplePhrases: readonly ["p95 inference latency is 38ms on a single A100, down from 312ms on the prior runtime.", "We replaced the streaming serializer with a batched protobuf path; throughput rose 4.2× under load.", "The result holds for context windows up to 32k tokens; beyond that, see appendix B."];
-    readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "engineering-update"];
+    readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "status-update"];
     readonly tags: readonly ["technical", "engineering", "research"];
 }, {
     readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -304,7 +304,7 @@ declare const tones: readonly [{
     readonly voiceCues: readonly ["Ask a question on the slide, then answer it on the next.", "Use second person — speak to the room, not at it.", "Lean on stories and concrete examples over abstract framing.", "Keep each idea to one short paragraph; let the dialog do the rest."];
     readonly avoid: readonly ["Lecture-style monologue across many bullets.", "Hedge-laden academic phrasing.", "Stuffing slides — leave room for the discussion.", "Inside-baseball references the room may not share."];
     readonly samplePhrases: readonly ["Why now? Two things changed in the last six months.", "Here's the part that surprised us — and what we did about it.", "If you take one thing from this section, take this."];
-    readonly recommendedNarratives: readonly ["all-hands", "company-intro", "weekly-progress", "performance-review"];
+    readonly recommendedNarratives: readonly ["focus", "company-intro", "weekly-progress", "performance-review"];
     readonly tags: readonly ["dialog", "podcast", "discussion"];
 }];
 declare const themes: readonly [{
@@ -9387,7 +9387,7 @@ declare const catalogs: {
         readonly technicalFluency: "high";
         readonly decisionPower: "advisory";
         readonly attentionBudgetMinutes: 45;
-        readonly recommendedNarratives: readonly ["engineering-update", "challenge-resolution", "innovation", "weekly-progress"];
+        readonly recommendedNarratives: readonly ["status-update", "challenge-resolution", "innovation", "weekly-progress"];
         readonly recommendedTones: readonly ["technical", "casual", "conversational"];
         readonly tags: readonly ["internal", "engineering", "practitioner"];
     }, {
@@ -9602,7 +9602,7 @@ declare const catalogs: {
         readonly voiceCues: readonly ["Use first and second person.", "Use contractions ('we're', 'it's', 'don't').", "Favor short sentences and active voice.", "Frame metrics with a human-scale anchor when possible."];
         readonly avoid: readonly ["Stiff corporate jargon.", "Long compound sentences.", "Overuse of superlatives.", "Bureaucratic passive voice."];
         readonly samplePhrases: readonly ["We shipped the new dashboard last week, and customers are already moving over.", "Here's where we ended up on hiring this quarter.", "It's been a busy month — here's the recap."];
-        readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "all-hands"];
+        readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "focus"];
         readonly tags: readonly ["internal", "warm", "conversational"];
     }, {
         readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -9624,7 +9624,7 @@ declare const catalogs: {
         readonly voiceCues: readonly ["State the claim, then the mechanism, then the evidence.", "Use exact terminology — don't soften technical terms for general readability.", "Quote benchmarks with conditions (cold/warm, p50/p95/p99, dataset, hardware).", "Prefer diagrams and tables over prose paragraphs for structural information."];
         readonly avoid: readonly ["Vague claims ('much faster', 'better', 'easier').", "Marketing framing without supporting data.", "Glossing over caveats and tradeoffs.", "Casual register that obscures precision."];
         readonly samplePhrases: readonly ["p95 inference latency is 38ms on a single A100, down from 312ms on the prior runtime.", "We replaced the streaming serializer with a batched protobuf path; throughput rose 4.2× under load.", "The result holds for context windows up to 32k tokens; beyond that, see appendix B."];
-        readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "engineering-update"];
+        readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "status-update"];
         readonly tags: readonly ["technical", "engineering", "research"];
     }, {
         readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -9657,7 +9657,7 @@ declare const catalogs: {
         readonly voiceCues: readonly ["Ask a question on the slide, then answer it on the next.", "Use second person — speak to the room, not at it.", "Lean on stories and concrete examples over abstract framing.", "Keep each idea to one short paragraph; let the dialog do the rest."];
         readonly avoid: readonly ["Lecture-style monologue across many bullets.", "Hedge-laden academic phrasing.", "Stuffing slides — leave room for the discussion.", "Inside-baseball references the room may not share."];
         readonly samplePhrases: readonly ["Why now? Two things changed in the last six months.", "Here's the part that surprised us — and what we did about it.", "If you take one thing from this section, take this."];
-        readonly recommendedNarratives: readonly ["all-hands", "company-intro", "weekly-progress", "performance-review"];
+        readonly recommendedNarratives: readonly ["focus", "company-intro", "weekly-progress", "performance-review"];
         readonly tags: readonly ["dialog", "podcast", "discussion"];
     }];
     readonly themes: readonly [{
@@ -20901,7 +20901,7 @@ declare const catalogEntries: readonly [{
         readonly technicalFluency: "high";
         readonly decisionPower: "advisory";
         readonly attentionBudgetMinutes: 45;
-        readonly recommendedNarratives: readonly ["engineering-update", "challenge-resolution", "innovation", "weekly-progress"];
+        readonly recommendedNarratives: readonly ["status-update", "challenge-resolution", "innovation", "weekly-progress"];
         readonly recommendedTones: readonly ["technical", "casual", "conversational"];
         readonly tags: readonly ["internal", "engineering", "practitioner"];
     }, {
@@ -21233,7 +21233,7 @@ declare const catalogEntries: readonly [{
         readonly voiceCues: readonly ["Use first and second person.", "Use contractions ('we're', 'it's', 'don't').", "Favor short sentences and active voice.", "Frame metrics with a human-scale anchor when possible."];
         readonly avoid: readonly ["Stiff corporate jargon.", "Long compound sentences.", "Overuse of superlatives.", "Bureaucratic passive voice."];
         readonly samplePhrases: readonly ["We shipped the new dashboard last week, and customers are already moving over.", "Here's where we ended up on hiring this quarter.", "It's been a busy month — here's the recap."];
-        readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "all-hands"];
+        readonly recommendedNarratives: readonly ["weekly-progress", "status-update", "company-intro", "focus"];
         readonly tags: readonly ["internal", "warm", "conversational"];
     }, {
         readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -21255,7 +21255,7 @@ declare const catalogEntries: readonly [{
         readonly voiceCues: readonly ["State the claim, then the mechanism, then the evidence.", "Use exact terminology — don't soften technical terms for general readability.", "Quote benchmarks with conditions (cold/warm, p50/p95/p99, dataset, hardware).", "Prefer diagrams and tables over prose paragraphs for structural information."];
         readonly avoid: readonly ["Vague claims ('much faster', 'better', 'easier').", "Marketing framing without supporting data.", "Glossing over caveats and tradeoffs.", "Casual register that obscures precision."];
         readonly samplePhrases: readonly ["p95 inference latency is 38ms on a single A100, down from 312ms on the prior runtime.", "We replaced the streaming serializer with a batched protobuf path; throughput rose 4.2× under load.", "The result holds for context windows up to 32k tokens; beyond that, see appendix B."];
-        readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "engineering-update"];
+        readonly recommendedNarratives: readonly ["challenge-resolution", "innovation", "conference-talk", "status-update"];
         readonly tags: readonly ["technical", "engineering", "research"];
     }, {
         readonly $schema: "https://openpresentation.org/schema/opf-tone/v1";
@@ -21288,7 +21288,7 @@ declare const catalogEntries: readonly [{
         readonly voiceCues: readonly ["Ask a question on the slide, then answer it on the next.", "Use second person — speak to the room, not at it.", "Lean on stories and concrete examples over abstract framing.", "Keep each idea to one short paragraph; let the dialog do the rest."];
         readonly avoid: readonly ["Lecture-style monologue across many bullets.", "Hedge-laden academic phrasing.", "Stuffing slides — leave room for the discussion.", "Inside-baseball references the room may not share."];
         readonly samplePhrases: readonly ["Why now? Two things changed in the last six months.", "Here's the part that surprised us — and what we did about it.", "If you take one thing from this section, take this."];
-        readonly recommendedNarratives: readonly ["all-hands", "company-intro", "weekly-progress", "performance-review"];
+        readonly recommendedNarratives: readonly ["focus", "company-intro", "weekly-progress", "performance-review"];
         readonly tags: readonly ["dialog", "podcast", "discussion"];
     }];
     readonly index: {

package/dist/catalogs.js

@@ -63,7 +63,7 @@ var audiences = [
     "decisionPower": "advisory",
     "attentionBudgetMinutes": 45,
     "recommendedNarratives": [
-      "engineering-update",
+      "status-update",
       "challenge-resolution",
       "innovation",
       "weekly-progress"
@@ -579,7 +579,7 @@ var tones = [
       "weekly-progress",
       "status-update",
       "company-intro",
-      "all-hands"
+      "focus"
     ],
     "tags": [
       "internal",
@@ -649,7 +649,7 @@ var tones = [
       "challenge-resolution",
       "innovation",
       "conference-talk",
-      "engineering-update"
+      "status-update"
     ],
     "tags": [
       "technical",
@@ -752,7 +752,7 @@ var tones = [
       "If you take one thing from this section, take this."
     ],
     "recommendedNarratives": [
-      "all-hands",
+      "focus",
       "company-intro",
       "weekly-progress",
       "performance-review"