@cratis/scene.engine 4.38.0 → 4.39.0

package/blueprints/BlueprintCatalogEntry.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** One screen of a blueprint's screen set, as the gallery lists it. */
+export interface BlueprintCatalogScreen {
+    name: string;
+    title: string;
+    description?: string;
+    template?: string;
+    parent?: string;
+    order?: number;
+}
+
+/** One template a blueprint provides, as the gallery lists it. */
+export interface BlueprintCatalogTemplate {
+    name: string;
+    kind: string;
+    displayName?: string;
+    description?: string;
+    type?: string;
+    category?: string;
+    thumbnail?: string;
+}
+
+/** One sample-data pack a blueprint ships, as the gallery's preview-data selector lists it. */
+export interface BlueprintCatalogSampleData {
+    id: string;
+    title: string;
+    locale: string;
+    path: string;
+    default: boolean;
+}
+
+/**
+ * One domain blueprint as the gallery and the CLI documentation read it: what it is, how to show it, what it brings and what it needs.
+ * This is the shape of an entry of `blueprintCatalog.json`.
+ */
+export interface BlueprintCatalogEntry {
+    package: string;
+    version: string;
+    domain: string;
+    displayName?: string;
+    description: string;
+    thumbnail: string;
+    license?: string;
+    licenseUrl?: string;
+    dependencies: { name: string; versionRange?: string }[];
+    screens: BlueprintCatalogScreen[];
+    templates: BlueprintCatalogTemplate[];
+    sampleData: BlueprintCatalogSampleData[];
+}
+
+/** The file a blueprint package ships and the gallery reads: every domain blueprint the build knows, in package name order. */
+export interface BlueprintCatalogFile {
+    /** The version of this file's shape; a reader refuses a newer one. */
+    schema: 1;
+    blueprints: BlueprintCatalogEntry[];
+}

package/blueprints/BlueprintSource.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack, Screen } from '@cratis/scene.model';
+import { TemplateSource } from '../templates/TemplateSource';
+
+/**
+ * A blueprint package as the verification and the catalog read it: its manifest and the layouts and templates it provides (as a
+ * {@link TemplateSource}), plus what a manifest only names - the screens of its screen set, the sample-data packs its references point
+ * to, and the package's files. A React `ScenePackageBundle` already has most of this, so hosts pass their bundles straight in.
+ */
+export interface BlueprintSource extends TemplateSource {
+    /** The screens the package provides. When given, every screen of the screen set must be among them. */
+    screens?: Screen[];
+
+    /** The sample-data packs the manifest's references point to, loaded. */
+    packs?: SampleDataPack[];
+
+    /**
+     * The package-relative paths of the files the package contains (`thumbnails/crm.svg`, `sampleData/crm.en.json`). When given, the
+     * thumbnails and sample-data files the manifest names must be among them.
+     */
+    files?: string[];
+}

package/blueprints/blueprintRules.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The name of the package that provides the foundation layouts and templates every domain blueprint builds on. */
+export const foundationPackageName = 'Cratis.Blueprint.Default';
+
+/** The template types a domain blueprint may declare (Part B 1.2). */
+export const blueprintTemplateTypes: readonly string[] = ['Shell', 'Workspace', 'Dashboard', 'List', 'Board', 'Detail', 'Form', 'Wizard', 'Dialog', 'Auth', 'State'];
+
+/** The prefix every template category of a domain blueprint starts with; the rest is the domain. */
+export const businessCategoryPrefix = 'Business / ';
+
+/** The longest a blueprint description may be. */
+export const maximumBlueprintDescriptionLength = 200;
+
+const domainPattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const thumbnailPattern = /^thumbnails\/[A-Za-z0-9][A-Za-z0-9._-]*\.(png|webp|jpg|svg)$/;
+
+/** Whether a value is a lower-case domain slug: `crm`, `project-tracker`. */
+export const isValidBlueprintDomain = (domain: string | undefined): boolean => domain !== undefined && domainPattern.test(domain);
+
+/** Whether a value is a package-relative thumbnail path: `thumbnails/<name>.png`, `.webp`, `.jpg` or `.svg`. */
+export const isValidThumbnailPath = (path: string | undefined): boolean => path !== undefined && thumbnailPattern.test(path);

package/blueprints/describeBlueprintCatalog.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind } from '@cratis/scene.model';
+import { TemplateSource } from '../templates/TemplateSource';
+import { BlueprintCatalogEntry, BlueprintCatalogFile } from './BlueprintCatalogEntry';
+
+/**
+ * Describes every domain blueprint among the given packages - those of kind Blueprint that declare blueprint metadata - for a gallery:
+ * its thumbnail and description, its screen set in navigation order, the templates it provides, and the sample data a preview can use.
+ * A package that only provides foundation layouts and templates is not a domain blueprint and is not listed. The result is ordered by
+ * package name so the file it is written to is stable. The C# engine (`BlueprintCatalog.Describe`) returns the same entries; both are
+ * asserted against `blueprint-verification-fixtures.json`.
+ */
+export function describeBlueprintCatalog(sources: readonly TemplateSource[]): BlueprintCatalogEntry[] {
+    return sources
+        .filter(source => source.manifest.kind === PackageKind.Blueprint && source.manifest.blueprint !== undefined)
+        .map((source): BlueprintCatalogEntry => {
+            const manifest = source.manifest;
+            const blueprint = manifest.blueprint!;
+            const defaultId = blueprint.defaultSampleData ?? ((manifest.sampleData ?? []).length === 1 ? manifest.sampleData![0].id : undefined);
+            const templates = [
+                ...(source.layouts ?? []).map(template => ({ kind: 'Layout', template })),
+                ...(source.screenTemplates ?? []).map(template => ({ kind: 'ScreenTemplate', template })),
+                ...(source.dialogTemplates ?? []).map(template => ({ kind: 'DialogTemplate', template })),
+            ];
+
+            return {
+                package: manifest.name,
+                version: manifest.version,
+                domain: blueprint.domain,
+                ...(manifest.displayName === undefined ? {} : { displayName: manifest.displayName }),
+                description: blueprint.description,
+                thumbnail: blueprint.thumbnail,
+                ...(manifest.license === undefined ? {} : { license: manifest.license }),
+                ...(manifest.licenseUrl === undefined ? {} : { licenseUrl: manifest.licenseUrl }),
+                dependencies: manifest.dependencies.map(dependency => ({ name: dependency.name, ...(dependency.versionRange === undefined ? {} : { versionRange: dependency.versionRange }) })),
+                screens: orderedScreens(blueprint.screenSet ?? []).map(screen => ({
+                    name: screen.name,
+                    title: screen.title,
+                    ...(screen.description === undefined ? {} : { description: screen.description }),
+                    ...(screen.template === undefined ? {} : { template: screen.template }),
+                    ...(screen.parent === undefined ? {} : { parent: screen.parent }),
+                    ...(screen.order === undefined ? {} : { order: screen.order }),
+                })),
+                templates: templates.map(({ kind, template }) => {
+                    const described = template as { displayName?: string; description?: string; metadata?: { type?: string; category?: string; thumbnail?: string } };
+                    return {
+                        name: template.name,
+                        kind,
+                        ...(described.displayName === undefined ? {} : { displayName: described.displayName }),
+                        ...(described.description === undefined ? {} : { description: described.description }),
+                        ...(described.metadata?.type === undefined ? {} : { type: described.metadata.type }),
+                        ...(described.metadata?.category === undefined ? {} : { category: described.metadata.category }),
+                        ...(described.metadata?.thumbnail === undefined ? {} : { thumbnail: described.metadata.thumbnail }),
+                    };
+                }),
+                sampleData: (manifest.sampleData ?? []).map(reference => ({ id: reference.id, title: reference.title, locale: reference.locale, path: reference.path, default: reference.id === defaultId })),
+            };
+        })
+        .sort((left, right) => (left.package < right.package ? -1 : left.package > right.package ? 1 : 0));
+}
+
+/** The catalog as the file a blueprint package ships. */
+export const toBlueprintCatalogFile = (entries: BlueprintCatalogEntry[]): BlueprintCatalogFile => ({ schema: 1, blueprints: entries });
+
+/**
+ * Puts screens in navigation order: siblings by `order` (a screen without one keeps its written place after those with one), each
+ * screen directly followed by its children, so a flat list reads top to bottom as the navigation does.
+ */
+function orderedScreens<T extends { name: string; parent?: string; order?: number }>(screens: readonly T[]): T[] {
+    const names = new Set(screens.map(screen => screen.name));
+    const childrenOf = (parent: string | undefined): T[] => {
+        const siblings = screens.filter(screen => (parent === undefined ? screen.parent === undefined || !names.has(screen.parent) : screen.parent === parent));
+        return siblings
+            .map((screen, index) => ({ screen, index }))
+            .sort((left, right) => (left.screen.order ?? Number.MAX_SAFE_INTEGER) - (right.screen.order ?? Number.MAX_SAFE_INTEGER) || left.index - right.index)
+            .map(entry => entry.screen);
+    };
+
+    const result: T[] = [];
+    const seen = new Set<string>();
+    const walk = (level: T[]) => {
+        for (const screen of level) {
+            if (seen.has(screen.name)) continue;
+            seen.add(screen.name);
+            result.push(screen);
+            walk(childrenOf(screen.name));
+        }
+    };
+
+    walk(childrenOf(undefined));
+    for (const screen of screens) if (!seen.has(screen.name)) result.push(screen);
+    return result;
+}

package/blueprints/evaluateBlueprintPin.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { compareVersions, isValidVersion, isValidVersionRange, isVersionSatisfiedBy } from '../packageVersionRange';
+
+/** Where a blueprint reference's pin stands against what is installed and what is available. */
+export enum BlueprintPinStatus {
+    /** The installed version satisfies the pin and nothing newer is available. */
+    Current = 'Current',
+
+    /** A newer version the pin allows is available: taking it changes nothing the pin promised to keep. */
+    UpdateAvailable = 'UpdateAvailable',
+
+    /** A newer version is available that the pin does not allow - usually a new major version - so taking it is a deliberate move that rewrites the pin. */
+    UpdateBlockedByPin = 'UpdateBlockedByPin',
+
+    /** The installed version does not satisfy the pin: the reference was chosen from a version that is no longer there. */
+    NotSatisfied = 'NotSatisfied',
+
+    /** The pin or a version is not one the engine understands. */
+    Invalid = 'Invalid',
+}
+
+/** The outcome of evaluating a pin. */
+export interface BlueprintPinEvaluation {
+    status: BlueprintPinStatus;
+
+    /** The pin that was evaluated: the one given, or the default for the installed version when none was. */
+    pin: string;
+
+    /** Said in a sentence, for a tooltip or a diagnostic. */
+    message: string;
+}
+
+/**
+ * The pin a reference gets when a template is chosen from a blueprint: the caret range of the installed version, so the reference accepts
+ * every compatible update and refuses a new major version until someone moves it on purpose.
+ */
+export const defaultBlueprintPin = (installedVersion: string): string => `^${installedVersion}`;
+
+/**
+ * Decides whether "update available" applies to a template reference that pins a blueprint version (`TemplateReference.version`).
+ *
+ * A reference without a pin is held to {@link defaultBlueprintPin} of the installed version. The pin says which versions the reference
+ * is content to run against; the installed version must satisfy it, and a newer available version is an update - an ordinary one when
+ * the pin allows it, one the pin blocks (usually a major version) when it does not. Both engines implement this identically (`BlueprintVersionPin.Evaluate`) and are
+ * asserted against `blueprint-verification-fixtures.json`.
+ *
+ * @param pin The reference's version range, or undefined when it has none.
+ * @param installedVersion The version of the blueprint that is installed.
+ * @param latestVersion The newest version of the blueprint that is available; when undefined only the installed version is known.
+ */
+export function evaluateBlueprintPin(pin: string | undefined, installedVersion: string, latestVersion?: string): BlueprintPinEvaluation {
+    const effective = pin === undefined || pin.trim() === '' ? defaultBlueprintPin(installedVersion) : pin.trim();
+
+    if (!isValidVersion(installedVersion)) return { status: BlueprintPinStatus.Invalid, pin: effective, message: `Installed version '${installedVersion}' is not a version` };
+    if (!isValidVersionRange(effective)) return { status: BlueprintPinStatus.Invalid, pin: effective, message: `Pin '${effective}' is not a version range` };
+    if (latestVersion !== undefined && !isValidVersion(latestVersion)) return { status: BlueprintPinStatus.Invalid, pin: effective, message: `Latest version '${latestVersion}' is not a version` };
+
+    if (!isVersionSatisfiedBy(installedVersion, effective)) {
+        return { status: BlueprintPinStatus.NotSatisfied, pin: effective, message: `Version ${installedVersion} is installed but the reference pins ${effective}` };
+    }
+
+    if (latestVersion === undefined || compareVersions(latestVersion, installedVersion) <= 0) {
+        return { status: BlueprintPinStatus.Current, pin: effective, message: `Version ${installedVersion} is the latest` };
+    }
+
+    return isVersionSatisfiedBy(latestVersion, effective)
+        ? { status: BlueprintPinStatus.UpdateAvailable, pin: effective, message: `Version ${latestVersion} is available, and ${effective} allows it` }
+        : { status: BlueprintPinStatus.UpdateBlockedByPin, pin: effective, message: `Version ${latestVersion} is available but ${effective} does not allow it` };
+}

package/blueprints/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './BlueprintSource';
+export * from './BlueprintCatalogEntry';
+export * from './blueprintRules';
+export * from './verifyBlueprintPackage';
+export * from './describeBlueprintCatalog';
+export * from './evaluateBlueprintPin';

package/blueprints/verifyBlueprintPackage.ts

@@ -0,0 +1,192 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScreenTemplate } from '@cratis/scene.model';
+import { isValidVersion } from '../packageVersionRange';
+import { resolveScreenTemplates } from '../resolveScreenTemplates';
+import { validateSampleDataPackages } from '../sampleData/validateSampleDataPackages';
+import { describeTemplateCatalog } from '../templates/describeTemplateCatalog';
+import { TemplateSource } from '../templates/TemplateSource';
+import { BlueprintSource } from './BlueprintSource';
+import {
+    blueprintTemplateTypes, businessCategoryPrefix, foundationPackageName, isValidBlueprintDomain, isValidThumbnailPath, maximumBlueprintDescriptionLength,
+} from './blueprintRules';
+
+/** How a blueprint is verified. */
+export interface BlueprintVerificationOptions {
+    /** The package that provides the foundation set a domain blueprint must depend on. Defaults to {@link foundationPackageName}. */
+    foundationPackage?: string;
+
+    /** Whether a package without blueprint metadata is a problem. Set for every domain blueprint; unset for a package that only provides foundation layouts and templates. */
+    requireBlueprintMetadata?: boolean;
+}
+
+/**
+ * The definition of done for a blueprint (spec Part B 6), as rules a package can be held to: valid manifest and version; for a domain
+ * blueprint its domain, description, thumbnail and screen set; every template with complete metadata, a category, a type from the
+ * vocabulary, a description and a thumbnail; every template placed by the slot resolver, with nothing unplaced, ambiguous or nested in
+ * itself (ambiguity is only a problem for a domain blueprint: the foundation's generic nesting chain fits slots many templates declare, and is chosen explicitly); sample data present, locale-tagged and valid; and a dependency on the foundation set. The C# engine
+ * (`BlueprintVerification.Verify`) reports the same problems in the same order; both are asserted against
+ * `blueprint-verification-fixtures.json`.
+ *
+ * @param source The blueprint to verify.
+ * @param library The other packages available - above all the foundation set - so templates can be placed into its layouts and checked against its versions.
+ * @param options How strictly to verify.
+ * @returns The problems; empty when the blueprint is done.
+ */
+export function verifyBlueprintPackage(source: BlueprintSource, library: readonly TemplateSource[] = [], options: BlueprintVerificationOptions = {}): string[] {
+    const manifest = source.manifest;
+    const name = manifest.name;
+    const label = `Blueprint '${name}'`;
+    const foundation = options.foundationPackage ?? foundationPackageName;
+
+    if (manifest.kind !== PackageKind.Blueprint) return [`Package '${name}' is not a Blueprint package`];
+
+    const problems: string[] = [];
+    if (!isValidVersion(manifest.version)) problems.push(`${label} declares an invalid version '${manifest.version ?? ''}'`);
+
+    const blueprint = manifest.blueprint;
+    const domain = blueprint !== undefined;
+    const available = new Set([...(source.screenTemplates ?? []), ...library.flatMap(other => other.screenTemplates ?? [])].map(template => template.name));
+
+    if (!blueprint) {
+        if (options.requireBlueprintMetadata) problems.push(`${label} declares no blueprint metadata (domain, description, thumbnail and screen set)`);
+    } else {
+        if ((blueprint.domain ?? '').trim() === '') problems.push(`${label} declares no domain`);
+        else if (!isValidBlueprintDomain(blueprint.domain)) problems.push(`${label} declares an invalid domain '${blueprint.domain}'; use lower-case words separated by '-'`);
+
+        if ((blueprint.description ?? '').trim() === '') problems.push(`${label} declares no description`);
+        else if (blueprint.description.length > maximumBlueprintDescriptionLength) problems.push(`${label} declares a description longer than ${maximumBlueprintDescriptionLength} characters`);
+
+        problems.push(...thumbnailProblems(label, blueprint.thumbnail, source.files));
+        problems.push(...screenSetProblems(source, label, available));
+
+        if (blueprint.defaultSampleData !== undefined && !(manifest.sampleData ?? []).some(reference => reference.id === blueprint.defaultSampleData)) {
+            problems.push(`${label} declares default sample data '${blueprint.defaultSampleData}', which is not one of its sample data packs`);
+        }
+
+        if ((manifest.sampleData ?? []).length === 0) problems.push(`${label} ships no sample data pack`);
+        else if ((manifest.sampleData ?? []).length > 1 && blueprint.defaultSampleData === undefined) problems.push(`${label} ships several sample data packs but declares no default`);
+
+        if (name !== foundation && !manifest.dependencies.some(dependency => dependency.name === foundation)) {
+            problems.push(`${label} does not depend on the foundation set '${foundation}'`);
+        }
+    }
+
+    problems.push(...validateSampleDataPackages([{ manifest, packs: source.packs }]));
+    for (const reference of manifest.sampleData ?? []) {
+        if (source.files !== undefined && !source.files.includes(reference.path)) problems.push(`${label} sample data pack '${reference.id}' names '${reference.path}', which is not in the package`);
+    }
+
+    problems.push(...templateProblems(source, library, domain));
+    problems.push(...placementProblems(source, library, label, domain));
+    return problems;
+}
+
+function thumbnailProblems(owner: string, thumbnail: string | undefined, files: string[] | undefined): string[] {
+    if ((thumbnail ?? '').trim() === '') return [`${owner} declares no thumbnail`];
+    if (!isValidThumbnailPath(thumbnail)) return [`${owner} declares thumbnail '${thumbnail}', which is not 'thumbnails/<name>.png|webp|jpg|svg'`];
+    if (files !== undefined && !files.includes(thumbnail!)) return [`${owner} declares thumbnail '${thumbnail}', which is not in the package`];
+    return [];
+}
+
+function screenSetProblems(source: BlueprintSource, label: string, availableTemplates: Set<string>): string[] {
+    const set = source.manifest.blueprint!.screenSet ?? [];
+    if (set.length === 0) return [`${label} declares no ready-to-use screen set`];
+
+    const problems: string[] = [];
+    const names = new Set<string>();
+    for (const screen of set) {
+        if ((screen.name ?? '').trim() === '') {
+            problems.push(`${label} declares a screen set entry without a name`);
+            continue;
+        }
+
+        if (names.has(screen.name)) problems.push(`${label} declares screen '${screen.name}' more than once`);
+        names.add(screen.name);
+    }
+
+    for (const screen of set) {
+        if ((screen.name ?? '').trim() === '') continue;
+        const owner = `${label} screen '${screen.name}'`;
+        if ((screen.title ?? '').trim() === '') problems.push(`${owner} declares no title`);
+        if (screen.template !== undefined && !availableTemplates.has(screen.template)) problems.push(`${owner} uses template '${screen.template}', which is not available`);
+        if (screen.parent !== undefined && !names.has(screen.parent)) problems.push(`${owner} has parent '${screen.parent}', which is not in the screen set`);
+        if (source.screens !== undefined && !source.screens.some(candidate => candidate.name === screen.name)) problems.push(`${owner} is named in the screen set but the package does not provide it`);
+    }
+
+    for (const screen of set) {
+        if (screen.parent !== undefined && names.has(screen.parent) && isOwnAncestor(screen.name, set)) problems.push(`${label} screen '${screen.name}' is its own ancestor`);
+    }
+
+    return problems;
+}
+
+function isOwnAncestor(name: string, set: { name: string; parent?: string }[]): boolean {
+    const visited = new Set<string>();
+    for (let current = set.find(screen => screen.name === name)?.parent; current !== undefined; current = set.find(screen => screen.name === current)?.parent) {
+        if (current === name) return true;
+        if (visited.has(current)) return false;
+        visited.add(current);
+    }
+
+    return false;
+}
+
+function templateProblems(source: BlueprintSource, library: readonly TemplateSource[], domain: boolean): string[] {
+    const problems: string[] = [];
+    const described = [...(source.screenTemplates ?? []), ...(source.dialogTemplates ?? [])];
+    const everyTemplate: { name: string; displayName?: string; description?: string; metadata?: { type?: string; category?: string; thumbnail?: string }; describable: boolean }[] = [
+        ...(source.layouts ?? []).map(layout => ({ name: layout.name, metadata: layout.metadata, describable: false })),
+        ...described.map(template => ({ name: template.name, displayName: template.displayName, description: template.description, metadata: template.metadata, describable: true })),
+    ];
+
+    const others = library.filter(other => other.manifest.name !== source.manifest.name);
+    for (const entry of describeTemplateCatalog([source, ...others]).filter(candidate => candidate.package === source.manifest.name)) {
+        problems.push(...entry.problems);
+    }
+
+    for (const template of everyTemplate) {
+        const owner = `Template '${template.name}'`;
+        if (template.describable && (template.displayName ?? '').trim() === '') problems.push(`${owner} declares no display name`);
+        if (template.describable && (template.description ?? '').trim() === '') problems.push(`${owner} declares no description`);
+        if (!domain) continue;
+
+        const metadata = template.metadata;
+        if (metadata?.type === undefined) problems.push(`${owner} declares no type`);
+        else if (!blueprintTemplateTypes.includes(metadata.type)) problems.push(`${owner} declares type '${metadata.type}', which is not one of ${blueprintTemplateTypes.join(', ')}`);
+
+        if (metadata?.category !== undefined && metadata.category.trim() !== '' && !metadata.category.startsWith(businessCategoryPrefix)) {
+            problems.push(`${owner} declares category '${metadata.category}', which does not start with '${businessCategoryPrefix}'`);
+        }
+
+        problems.push(...thumbnailProblems(owner, metadata?.thumbnail, source.files));
+    }
+
+    return problems;
+}
+
+function placementProblems(source: BlueprintSource, library: readonly TemplateSource[], label: string, domain: boolean): string[] {
+    const own: ScreenTemplate[] = (source.screenTemplates ?? []).filter(template => template.fitsSlot !== undefined);
+    if (own.length === 0) return [];
+
+    const layouts = [...(source.layouts ?? []), ...library.flatMap(other => other.layouts ?? [])];
+    const everyTemplate = [...(source.screenTemplates ?? []), ...library.flatMap(other => other.screenTemplates ?? [])];
+    if (layouts.length === 0) return [`${label} has no layout to place its screen templates in`];
+
+    const resolutions = layouts.map(layout => ({ layout, resolution: resolveScreenTemplates(layout, everyTemplate) }));
+    const problems: string[] = [];
+
+    for (const template of own) {
+        if (resolutions.some(({ resolution }) => resolution.placements.some(placement => placement.template === template.name))) continue;
+
+        const unplacedEverywhere = resolutions.flatMap(({ resolution }) => resolution.unplaced.filter(candidate => candidate.template === template.name));
+        const unplaced = unplacedEverywhere.find(candidate => candidate.candidates.length > 1);
+        const cyclic = resolutions.some(({ resolution }) => resolution.cycles.some(cycle => cycle.includes(template.name)));
+        if (cyclic) problems.push(`Template '${template.name}' is nested inside itself`);
+        else if (unplaced && domain) problems.push(`Template '${template.name}' is ambiguous: slot '${unplaced.slot}' is declared by ${unplaced.candidates.join(', ')}`);
+        else if (!unplaced) problems.push(`Template '${template.name}' is unplaced: no layout or template declares slot '${template.fitsSlot}'`);
+    }
+
+    return problems;
+}

package/dist/cjs/blueprints/blueprintRules.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/** The name of the package that provides the foundation layouts and templates every domain blueprint builds on. */ const foundationPackageName = 'Cratis.Blueprint.Default';
+/** The template types a domain blueprint may declare (Part B 1.2). */ const blueprintTemplateTypes = [
+    'Shell',
+    'Workspace',
+    'Dashboard',
+    'List',
+    'Board',
+    'Detail',
+    'Form',
+    'Wizard',
+    'Dialog',
+    'Auth',
+    'State'
+];
+/** The prefix every template category of a domain blueprint starts with; the rest is the domain. */ const businessCategoryPrefix = 'Business / ';
+/** The longest a blueprint description may be. */ const maximumBlueprintDescriptionLength = 200;
+const domainPattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const thumbnailPattern = /^thumbnails\/[A-Za-z0-9][A-Za-z0-9._-]*\.(png|webp|jpg|svg)$/;
+/** Whether a value is a lower-case domain slug: `crm`, `project-tracker`. */ const isValidBlueprintDomain = (domain)=>domain !== undefined && domainPattern.test(domain);
+/** Whether a value is a package-relative thumbnail path: `thumbnails/<name>.png`, `.webp`, `.jpg` or `.svg`. */ const isValidThumbnailPath = (path)=>path !== undefined && thumbnailPattern.test(path);
+
+exports.blueprintTemplateTypes = blueprintTemplateTypes;
+exports.businessCategoryPrefix = businessCategoryPrefix;
+exports.foundationPackageName = foundationPackageName;
+exports.isValidBlueprintDomain = isValidBlueprintDomain;
+exports.isValidThumbnailPath = isValidThumbnailPath;
+exports.maximumBlueprintDescriptionLength = maximumBlueprintDescriptionLength;
+//# sourceMappingURL=blueprintRules.js.map

package/dist/cjs/blueprints/blueprintRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprintRules.js","sources":["../../../blueprints/blueprintRules.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/** The name of the package that provides the foundation layouts and templates every domain blueprint builds on. */\nexport const foundationPackageName = 'Cratis.Blueprint.Default';\n\n/** The template types a domain blueprint may declare (Part B 1.2). */\nexport const blueprintTemplateTypes: readonly string[] = ['Shell', 'Workspace', 'Dashboard', 'List', 'Board', 'Detail', 'Form', 'Wizard', 'Dialog', 'Auth', 'State'];\n\n/** The prefix every template category of a domain blueprint starts with; the rest is the domain. */\nexport const businessCategoryPrefix = 'Business / ';\n\n/** The longest a blueprint description may be. */\nexport const maximumBlueprintDescriptionLength = 200;\n\nconst domainPattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;\nconst thumbnailPattern = /^thumbnails\\/[A-Za-z0-9][A-Za-z0-9._-]*\\.(png|webp|jpg|svg)$/;\n\n/** Whether a value is a lower-case domain slug: `crm`, `project-tracker`. */\nexport const isValidBlueprintDomain = (domain: string | undefined): boolean => domain !== undefined && domainPattern.test(domain);\n\n/** Whether a value is a package-relative thumbnail path: `thumbnails/<name>.png`, `.webp`, `.jpg` or `.svg`. */\nexport const isValidThumbnailPath = (path: string | undefined): boolean => path !== undefined && thumbnailPattern.test(path);\n"],"names":["foundationPackageName","blueprintTemplateTypes","businessCategoryPrefix","maximumBlueprintDescriptionLength","domainPattern","thumbnailPattern","isValidBlueprintDomain","domain","undefined","test","isValidThumbnailPath","path"],"mappings":";;AAAA;AACA;AAEA,oHACO,MAAMA,qBAAAA,GAAwB;AAErC,uEACO,MAAMC,sBAAAA,GAA4C;AAAC,IAAA,OAAA;AAAS,IAAA,WAAA;AAAa,IAAA,WAAA;AAAa,IAAA,MAAA;AAAQ,IAAA,OAAA;AAAS,IAAA,QAAA;AAAU,IAAA,MAAA;AAAQ,IAAA,QAAA;AAAU,IAAA,QAAA;AAAU,IAAA,MAAA;AAAQ,IAAA;;AAE5J,qGACO,MAAMC,sBAAAA,GAAyB;AAEtC,mDACO,MAAMC,iCAAAA,GAAoC;AAEjD,MAAMC,aAAAA,GAAgB,+BAAA;AACtB,MAAMC,gBAAAA,GAAmB,8DAAA;AAEzB,8EACO,MAAMC,sBAAAA,GAAyB,CAACC,MAAAA,GAAwCA,MAAAA,KAAWC,SAAAA,IAAaJ,aAAAA,CAAcK,IAAI,CAACF,MAAAA;AAE1H,iHACO,MAAMG,oBAAAA,GAAuB,CAACC,IAAAA,GAAsCA,IAAAA,KAASH,SAAAA,IAAaH,gBAAAA,CAAiBI,IAAI,CAACE,IAAAA;;;;;;;"}

package/dist/cjs/blueprints/describeBlueprintCatalog.js

@@ -0,0 +1,134 @@
+'use strict';
+
+var scene_model = require('@cratis/scene.model');
+
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Describes every domain blueprint among the given packages - those of kind Blueprint that declare blueprint metadata - for a gallery:
+ * its thumbnail and description, its screen set in navigation order, the templates it provides, and the sample data a preview can use.
+ * A package that only provides foundation layouts and templates is not a domain blueprint and is not listed. The result is ordered by
+ * package name so the file it is written to is stable. The C# engine (`BlueprintCatalog.Describe`) returns the same entries; both are
+ * asserted against `blueprint-verification-fixtures.json`.
+ */ function describeBlueprintCatalog(sources) {
+    return sources.filter((source)=>source.manifest.kind === scene_model.PackageKind.Blueprint && source.manifest.blueprint !== undefined).map((source)=>{
+        const manifest = source.manifest;
+        const blueprint = manifest.blueprint;
+        const defaultId = blueprint.defaultSampleData ?? ((manifest.sampleData ?? []).length === 1 ? manifest.sampleData[0].id : undefined);
+        const templates = [
+            ...(source.layouts ?? []).map((template)=>({
+                    kind: 'Layout',
+                    template
+                })),
+            ...(source.screenTemplates ?? []).map((template)=>({
+                    kind: 'ScreenTemplate',
+                    template
+                })),
+            ...(source.dialogTemplates ?? []).map((template)=>({
+                    kind: 'DialogTemplate',
+                    template
+                }))
+        ];
+        return {
+            package: manifest.name,
+            version: manifest.version,
+            domain: blueprint.domain,
+            ...manifest.displayName === undefined ? {} : {
+                displayName: manifest.displayName
+            },
+            description: blueprint.description,
+            thumbnail: blueprint.thumbnail,
+            ...manifest.license === undefined ? {} : {
+                license: manifest.license
+            },
+            ...manifest.licenseUrl === undefined ? {} : {
+                licenseUrl: manifest.licenseUrl
+            },
+            dependencies: manifest.dependencies.map((dependency)=>({
+                    name: dependency.name,
+                    ...dependency.versionRange === undefined ? {} : {
+                        versionRange: dependency.versionRange
+                    }
+                })),
+            screens: orderedScreens(blueprint.screenSet ?? []).map((screen)=>({
+                    name: screen.name,
+                    title: screen.title,
+                    ...screen.description === undefined ? {} : {
+                        description: screen.description
+                    },
+                    ...screen.template === undefined ? {} : {
+                        template: screen.template
+                    },
+                    ...screen.parent === undefined ? {} : {
+                        parent: screen.parent
+                    },
+                    ...screen.order === undefined ? {} : {
+                        order: screen.order
+                    }
+                })),
+            templates: templates.map(({ kind, template })=>{
+                const described = template;
+                return {
+                    name: template.name,
+                    kind,
+                    ...described.displayName === undefined ? {} : {
+                        displayName: described.displayName
+                    },
+                    ...described.description === undefined ? {} : {
+                        description: described.description
+                    },
+                    ...described.metadata?.type === undefined ? {} : {
+                        type: described.metadata.type
+                    },
+                    ...described.metadata?.category === undefined ? {} : {
+                        category: described.metadata.category
+                    },
+                    ...described.metadata?.thumbnail === undefined ? {} : {
+                        thumbnail: described.metadata.thumbnail
+                    }
+                };
+            }),
+            sampleData: (manifest.sampleData ?? []).map((reference)=>({
+                    id: reference.id,
+                    title: reference.title,
+                    locale: reference.locale,
+                    path: reference.path,
+                    default: reference.id === defaultId
+                }))
+        };
+    }).sort((left, right)=>left.package < right.package ? -1 : left.package > right.package ? 1 : 0);
+}
+/** The catalog as the file a blueprint package ships. */ const toBlueprintCatalogFile = (entries)=>({
+        schema: 1,
+        blueprints: entries
+    });
+/**
+ * Puts screens in navigation order: siblings by `order` (a screen without one keeps its written place after those with one), each
+ * screen directly followed by its children, so a flat list reads top to bottom as the navigation does.
+ */ function orderedScreens(screens) {
+    const names = new Set(screens.map((screen)=>screen.name));
+    const childrenOf = (parent)=>{
+        const siblings = screens.filter((screen)=>parent === undefined ? screen.parent === undefined || !names.has(screen.parent) : screen.parent === parent);
+        return siblings.map((screen, index)=>({
+                screen,
+                index
+            })).sort((left, right)=>(left.screen.order ?? Number.MAX_SAFE_INTEGER) - (right.screen.order ?? Number.MAX_SAFE_INTEGER) || left.index - right.index).map((entry)=>entry.screen);
+    };
+    const result = [];
+    const seen = new Set();
+    const walk = (level)=>{
+        for (const screen of level){
+            if (seen.has(screen.name)) continue;
+            seen.add(screen.name);
+            result.push(screen);
+            walk(childrenOf(screen.name));
+        }
+    };
+    walk(childrenOf(undefined));
+    for (const screen of screens)if (!seen.has(screen.name)) result.push(screen);
+    return result;
+}
+
+exports.describeBlueprintCatalog = describeBlueprintCatalog;
+exports.toBlueprintCatalogFile = toBlueprintCatalogFile;
+//# sourceMappingURL=describeBlueprintCatalog.js.map