@markii/pack 0.7.3 → 0.8.0

package/dist/components.d.ts

@@ -0,0 +1,81 @@
+import type { PackManifest } from './manifest.js';
+/**
+ * Which directive form a pack component is written as. Mirrors
+ * `@markii/stdlib`'s `ComponentKind`; defined locally here rather than
+ * imported because `@markii/pack` is a published, zero-dependency package
+ * (see AGENTS.md's Stack section) and `@markii/stdlib` is a sibling
+ * package, not a dependency of this one. The two unions must stay aligned;
+ * `@markii/host` (which depends on both) carries an executable check of
+ * that alignment, since this package cannot import `@markii/stdlib` to
+ * check it itself.
+ */
+export type PackComponentKind = 'inline' | 'leaf' | 'container';
+/**
+ * The three `kind` values, as runtime data. This is the ONE list: the
+ * manifest validator (`./manifest.ts`) checks a declared `kind` against it,
+ * and `@markii/host`'s alignment test compares it against
+ * `@markii/stdlib`'s `ComponentKind` members, so the values cannot be
+ * spelled differently in two places within this package and drift apart.
+ */
+export declare const PACK_COMPONENT_KINDS: readonly PackComponentKind[];
+/**
+ * The object form of a `components` manifest entry. `source` is the only
+ * required field (a pack-relative path, same meaning as the string
+ * shorthand); `description` and `kind` are optional metadata a host can
+ * surface in an insert-component catalog or similar UI.
+ */
+export interface PackComponentDefinition {
+    source: string;
+    description?: string;
+    kind?: PackComponentKind;
+}
+/**
+ * A `components` manifest entry: either the original string shorthand
+ * (source path only) or the object form carrying optional metadata
+ * alongside the source.
+ */
+export type PackComponentEntry = string | PackComponentDefinition;
+/**
+ * One component's declared metadata with both entry forms normalized to
+ * the same shape. `description`/`kind` are only present when the manifest
+ * declared them (the string shorthand never has either).
+ */
+export interface ResolvedPackComponent {
+    readonly source: string;
+    readonly description?: string;
+    readonly kind?: PackComponentKind;
+}
+/** Same as `ResolvedPackComponent`, plus the local name it was declared under. */
+export interface PackComponentListing extends ResolvedPackComponent {
+    readonly localName: string;
+}
+/**
+ * Normalizes a single `components` entry, string or object form, into the
+ * common `ResolvedPackComponent` shape. This is THE accessor for reading
+ * one entry — callers should never inline a `typeof entry === 'string'`
+ * check of their own, so the two forms cannot silently drift apart across
+ * consumers.
+ *
+ * Never throws and never assumes the input has already been validated by
+ * `parsePackManifest`: a hostile or malformed value (not a string, not a
+ * plain object, an object missing `source`, a `source` that is not a
+ * non-empty string) returns `undefined` rather than throwing or fabricating
+ * a value. This matters because a consumer may call this directly on
+ * attacker-controlled JSON that never went through `parsePackManifest` at
+ * all (for example a pack loaded from an untrusted bundle).
+ */
+export declare function resolvePackComponent(entry: unknown): ResolvedPackComponent | undefined;
+/**
+ * THE iterator every consumer uses instead of walking `manifest.components`
+ * directly: `Object.hasOwn`-guarded, in declaration key order, skipping any
+ * entry `resolvePackComponent` cannot resolve rather than throwing. This is
+ * the only sanctioned way to enumerate a pack's components — see
+ * `discover.ts`, `pack-build.ts`, `pack-diagnostics.ts`, and
+ * `component-catalog.ts` in `@markii/host`, all of which call this instead
+ * of re-implementing the walk.
+ *
+ * Tolerates a manifest whose `components` field is missing, `null`, not an
+ * object, or an array: all of those return `[]` rather than throwing, so a
+ * caller never needs to guard the call site itself.
+ */
+export declare function packComponents(manifest: Pick<PackManifest, 'components'>): PackComponentListing[];

package/dist/components.js

@@ -0,0 +1,92 @@
+/**
+ * The three `kind` values, as runtime data. This is the ONE list: the
+ * manifest validator (`./manifest.ts`) checks a declared `kind` against it,
+ * and `@markii/host`'s alignment test compares it against
+ * `@markii/stdlib`'s `ComponentKind` members, so the values cannot be
+ * spelled differently in two places within this package and drift apart.
+ */
+export const PACK_COMPONENT_KINDS = [
+    'inline',
+    'leaf',
+    'container',
+];
+const PACK_COMPONENT_KIND_SET = new Set(PACK_COMPONENT_KINDS);
+/**
+ * Normalizes a single `components` entry, string or object form, into the
+ * common `ResolvedPackComponent` shape. This is THE accessor for reading
+ * one entry — callers should never inline a `typeof entry === 'string'`
+ * check of their own, so the two forms cannot silently drift apart across
+ * consumers.
+ *
+ * Never throws and never assumes the input has already been validated by
+ * `parsePackManifest`: a hostile or malformed value (not a string, not a
+ * plain object, an object missing `source`, a `source` that is not a
+ * non-empty string) returns `undefined` rather than throwing or fabricating
+ * a value. This matters because a consumer may call this directly on
+ * attacker-controlled JSON that never went through `parsePackManifest` at
+ * all (for example a pack loaded from an untrusted bundle).
+ */
+export function resolvePackComponent(entry) {
+    if (typeof entry === 'string') {
+        return entry.length > 0 ? { source: entry } : undefined;
+    }
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        return undefined;
+    }
+    // Object.hasOwn only, matching this package's rule throughout: never read
+    // an inherited property, so an object built with a hostile prototype
+    // cannot smuggle a `source` through the prototype chain.
+    const source = Object.hasOwn(entry, 'source')
+        ? entry.source
+        : undefined;
+    if (typeof source !== 'string' || source.length === 0) {
+        return undefined;
+    }
+    const result = {
+        source,
+    };
+    const description = Object.hasOwn(entry, 'description')
+        ? entry.description
+        : undefined;
+    if (typeof description === 'string' && description.length > 0) {
+        result.description = description;
+    }
+    const kind = Object.hasOwn(entry, 'kind')
+        ? entry.kind
+        : undefined;
+    if (typeof kind === 'string' && PACK_COMPONENT_KIND_SET.has(kind)) {
+        result.kind = kind;
+    }
+    return result;
+}
+/**
+ * THE iterator every consumer uses instead of walking `manifest.components`
+ * directly: `Object.hasOwn`-guarded, in declaration key order, skipping any
+ * entry `resolvePackComponent` cannot resolve rather than throwing. This is
+ * the only sanctioned way to enumerate a pack's components — see
+ * `discover.ts`, `pack-build.ts`, `pack-diagnostics.ts`, and
+ * `component-catalog.ts` in `@markii/host`, all of which call this instead
+ * of re-implementing the walk.
+ *
+ * Tolerates a manifest whose `components` field is missing, `null`, not an
+ * object, or an array: all of those return `[]` rather than throwing, so a
+ * caller never needs to guard the call site itself.
+ */
+export function packComponents(manifest) {
+    const components = manifest?.components;
+    if (components === null ||
+        typeof components !== 'object' ||
+        Array.isArray(components)) {
+        return [];
+    }
+    const listings = [];
+    for (const localName of Object.keys(components)) {
+        if (!Object.hasOwn(components, localName))
+            continue;
+        const resolved = resolvePackComponent(components[localName]);
+        if (resolved === undefined)
+            continue;
+        listings.push({ localName, ...resolved });
+    }
+    return listings;
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export type { PackManifest, PackManifestParseResult } from './manifest.js';
 export { parsePackManifest } from './manifest.js';
+export type { PackComponentDefinition, PackComponentEntry, PackComponentKind, PackComponentListing, ResolvedPackComponent, } from './components.js';
+export { PACK_COMPONENT_KINDS, packComponents, resolvePackComponent, } from './components.js';
 export type { ComposeDirectiveNameResult, NamespaceCollision, NamespaceValidationResult, } from './namespace.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export type { UsesResolution } from './uses.js';

package/dist/index.js

@@ -3,5 +3,6 @@
 // hand-rolled validation only. No registry loading, no `uses:` surfacing,
 // no sandboxed `require`, no filesystem reads: those are later slices.
 export { parsePackManifest } from './manifest.js';
+export { PACK_COMPONENT_KINDS, packComponents, resolvePackComponent, } from './components.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/manifest.d.ts

@@ -1,3 +1,4 @@
+import type { PackComponentEntry } from './components.js';
 /**
  * `pack.json`'s contract (docs/packs.md). Three fields, all required:
  *
@@ -8,7 +9,10 @@
  * renderer framework the pack's components are written for; it is any
  * string — the host decides whether it can run it, so this package does
  * not maintain a closed enum of known engines. `components` maps a local
- * component name to a pack-relative source path.
+ * component name to either a pack-relative source path (the string
+ * shorthand) or an object carrying that source plus optional `description`/
+ * `kind` metadata (see `./components.ts`, `resolvePackComponent`,
+ * `packComponents`).
  *
  * Shared Lua modules are NOT a manifest field. docs/packs.md says they
  * travel under a conventional `scripts/` directory inside the pack
@@ -22,8 +26,14 @@ export interface PackManifest {
     name: string;
     /** The renderer framework the pack's components target, e.g. `"react"`. */
     engine: string;
-    /** Local component name -> pack-relative source path. */
-    components: Record<string, string>;
+    /**
+     * Local component name -> a pack-relative source path, or an object
+     * naming that source plus optional `description`/`kind` metadata. Read
+     * this map only through `resolvePackComponent`/`packComponents`
+     * (`./components.ts`) rather than inspecting entries directly — that is
+     * the one place both forms are normalized.
+     */
+    components: Record<string, PackComponentEntry>;
 }
 export type PackManifestParseResult = {
     ok: true;

package/dist/manifest.js

@@ -1,5 +1,14 @@
 import { validateLocalComponentName, validatePackName } from './namespace.js';
+import { PACK_COMPONENT_KINDS } from './components.js';
 const KNOWN_TOP_LEVEL_KEYS = new Set(['name', 'engine', 'components']);
+// The keys a component's object-form entry may carry, and which of those
+// are required. Mirrors KNOWN_TOP_LEVEL_KEYS's role for the manifest root:
+// an unrecognized key here is a forward-compatible warning, not an error.
+const KNOWN_COMPONENT_KEYS = new Set(['source', 'description', 'kind']);
+// Checked against ./components.ts's single runtime list rather than a second
+// copy of the three values, so the validator and the accessor can never
+// disagree about what a valid `kind` is.
+const PACK_COMPONENT_KIND_SET = new Set(PACK_COMPONENT_KINDS);
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -62,6 +71,18 @@ export function parsePackManifest(json) {
         engine = obj.engine;
     }
     // --- components (required) ---
+    //
+    // Each entry is either the string shorthand (a pack-relative source path)
+    // or an object form { source, description?, kind? }. A malformed entry —
+    // wrong value type, invalid key, bad `kind`, non-string `description`,
+    // missing/empty `source` in object form — pushes an error and rejects the
+    // WHOLE manifest, matching this file's existing posture for a bad
+    // top-level field. An unrecognized key INSIDE a component object is a
+    // forward-compatible warning, the same posture KNOWN_TOP_LEVEL_KEYS uses
+    // for the manifest root. Only the checked, sanitized fields are ever
+    // copied into `result`/the rebuilt component object — the raw parsed
+    // value is never stored, so an unknown or hostile key on a component
+    // object can never surface later even as inert data.
     let components;
     if (!Object.hasOwn(obj, 'components')) {
         errors.push('"components" is required');
@@ -83,17 +104,78 @@ export function parsePackManifest(json) {
                 continue;
             }
             const value = componentsObj[key];
-            if (typeof value !== 'string' || value.length === 0) {
-                errors.push(`"components.${key}" must be a non-empty string (a pack-relative source path)`);
+            if (typeof value === 'string') {
+                if (value.length === 0) {
+                    errors.push(`"components.${key}" must be a non-empty string (a pack-relative source path) or an object with a "source" field`);
+                    componentsValid = false;
+                    continue;
+                }
+                // Only the type is checked here, matching @markii/bundle's
+                // `document` field: path-jailing a pack-relative source path is a
+                // filesystem concern for the later registry-loading slice, not
+                // this contract-only one. Object.hasOwn above already keeps
+                // prototype members out of `result`.
+                result[key] = value;
+                continue;
+            }
+            if (!isPlainObject(value)) {
+                errors.push(`"components.${key}" must be a non-empty string (a pack-relative source path) or an object with a "source" field`);
+                componentsValid = false;
+                continue;
+            }
+            // Object form: validate source (required), description (optional),
+            // kind (optional), and rebuild a sanitized object rather than storing
+            // the raw parsed one — the same discipline as the string-form branch
+            // and as the top-level Object.hasOwn guarding throughout this file.
+            let entryValid = true;
+            const source = Object.hasOwn(value, 'source') ? value.source : undefined;
+            if (typeof source !== 'string' || source.length === 0) {
+                errors.push(`"components.${key}.source" must be a non-empty string (a pack-relative source path)`);
+                entryValid = false;
+            }
+            let description;
+            if (Object.hasOwn(value, 'description')) {
+                const rawDescription = value.description;
+                if (typeof rawDescription !== 'string' || rawDescription.length === 0) {
+                    errors.push(`"components.${key}.description" must be a non-empty string`);
+                    entryValid = false;
+                }
+                else {
+                    description = rawDescription;
+                }
+            }
+            let kind;
+            if (Object.hasOwn(value, 'kind')) {
+                const rawKind = value.kind;
+                if (typeof rawKind !== 'string' ||
+                    !PACK_COMPONENT_KIND_SET.has(rawKind)) {
+                    errors.push(`"components.${key}.kind" must be one of "inline", "leaf", "container"`);
+                    entryValid = false;
+                }
+                else {
+                    kind = rawKind;
+                }
+            }
+            for (const componentKey of Object.keys(value)) {
+                if (Object.hasOwn(value, componentKey) &&
+                    !KNOWN_COMPONENT_KEYS.has(componentKey)) {
+                    warnings.push(`unknown pack component key "components.${key}.${componentKey}" (ignored by this implementation)`);
+                }
+            }
+            if (!entryValid) {
                 componentsValid = false;
                 continue;
             }
-            // Only the type is checked here, matching @markii/bundle's
-            // `document` field: path-jailing a pack-relative source path is a
-            // filesystem concern for the later registry-loading slice, not this
-            // contract-only one. Object.hasOwn above already keeps prototype
-            // members out of `result`.
-            result[key] = value;
+            // The object form is kept as an object even when neither optional
+            // field was present — only the string shorthand collapses to a bare
+            // string. This preserves the author's declared form rather than
+            // silently normalizing `{ "source": "./x.tsx" }` into `"./x.tsx"`.
+            const sanitized = { source: source };
+            if (description !== undefined)
+                sanitized.description = description;
+            if (kind !== undefined)
+                sanitized.kind = kind;
+            result[key] = sanitized;
         }
         if (Object.keys(componentsObj).length === 0) {
             errors.push('"components" must have at least one entry');

package/dist/namespace.d.ts

@@ -3,7 +3,10 @@
  *
  * - Directive names MUST NOT contain `:` (reserved syntax).
  * - A namespaced directive name joins the pack's namespace and the
- *   component's local name with `-` or `_`.
+ *   component's local name with `_`, and only `_` (issue #19). The spec
+ *   permits `-` or `_` for a directive name generally; this package composes
+ *   exactly one of them, so the boundary between the two parts is always
+ *   unambiguous. See `composeDirectiveName` for why.
  * - The bundle's reserved first-path-segment names (`scripts`, `assets`,
  *   `.cache`) can never be a pack namespace, so a pack can never shadow
  *   bundle structure in `require` or in directive names.
@@ -20,11 +23,11 @@
  * hyphens as separators (no leading/trailing hyphen, no doubled hyphen).
  * This is deliberately conservative — it's stricter than the spec's bare
  * "MUST NOT contain `:`" requirement — because a namespace also has to
- * compose cleanly with a local name using `-` or `_` without producing an
- * ambiguous or surprising directive name. Underscore is accepted as the
- * separator when composing (`ana_timeline`) but is not accepted as a
- * character inside the namespace or local-name segments themselves, so the
- * composed name's own separator choice stays unambiguous.
+ * compose cleanly with a local name without producing an ambiguous or
+ * surprising directive name. Underscore is the composition separator
+ * (`ana_timeline`) and is deliberately NOT accepted inside the namespace or
+ * local-name segments themselves, which is exactly what makes the composed
+ * name's single underscore mark the boundary unambiguously.
  */
 /** The reserved bundle directory names a pack namespace must never collide with (spec.md §1, §8). */
 export declare const RESERVED_NAMESPACE_SEGMENTS: ReadonlySet<string>;
@@ -58,15 +61,29 @@ export type ComposeDirectiveNameResult = {
 };
 /**
  * Composes the directive name an author types to reference a pack's
- * component, e.g. `composeDirectiveName('ana', 'timeline')` -> `ana-timeline`
+ * component, e.g. `composeDirectiveName('ana', 'timeline')` -> `ana_timeline`
  * (docs/packs.md). Validates both inputs first, then the composed result
  * (defense in depth: the composed string must still contain no `:` and must
  * still be a legal directive-name shape).
  *
- * `separator` defaults to `-`; `_` is also accepted per spec.md §1's "joins
- * the namespace and name with `-` or `_`".
+ * The separator is `_`, and there is deliberately no way to ask for another
+ * one (issue #19, user-settled 2026-08-30). It used to be `-`, which is also
+ * the separator INSIDE a lowercase-kebab pack or local name, so two
+ * different packs could compose the same directive name: pack `long` plus
+ * component `pack-name-some-component` and pack `long-pack-name` plus
+ * component `some-component` both produced `long-pack-name-some-component`,
+ * and one silently shadowed the other. `SEGMENT_RE` bans `_` inside either
+ * segment, so an underscore join gives every composed name exactly one
+ * underscore, at the pack/component boundary. That makes the split
+ * bijective and this whole collision class impossible to construct rather
+ * than merely detected.
+ *
+ * Accepting both forms would have kept the ambiguity alive, so only this one
+ * exists. Notes and packs written against the old `-` composition stop
+ * resolving and render the labeled unknown-component fallback; that breakage
+ * was weighed and accepted pre-1.0 rather than carrying a migration shim.
  */
-export declare function composeDirectiveName(packName: string, localName: string, separator?: '-' | '_'): ComposeDirectiveNameResult;
+export declare function composeDirectiveName(packName: string, localName: string): ComposeDirectiveNameResult;
 export interface NamespaceCollision {
     namespace: string;
     /** How many times this namespace appears in the input. */

package/dist/namespace.js

@@ -3,7 +3,10 @@
  *
  * - Directive names MUST NOT contain `:` (reserved syntax).
  * - A namespaced directive name joins the pack's namespace and the
- *   component's local name with `-` or `_`.
+ *   component's local name with `_`, and only `_` (issue #19). The spec
+ *   permits `-` or `_` for a directive name generally; this package composes
+ *   exactly one of them, so the boundary between the two parts is always
+ *   unambiguous. See `composeDirectiveName` for why.
  * - The bundle's reserved first-path-segment names (`scripts`, `assets`,
  *   `.cache`) can never be a pack namespace, so a pack can never shadow
  *   bundle structure in `require` or in directive names.
@@ -20,11 +23,11 @@
  * hyphens as separators (no leading/trailing hyphen, no doubled hyphen).
  * This is deliberately conservative — it's stricter than the spec's bare
  * "MUST NOT contain `:`" requirement — because a namespace also has to
- * compose cleanly with a local name using `-` or `_` without producing an
- * ambiguous or surprising directive name. Underscore is accepted as the
- * separator when composing (`ana_timeline`) but is not accepted as a
- * character inside the namespace or local-name segments themselves, so the
- * composed name's own separator choice stays unambiguous.
+ * compose cleanly with a local name without producing an ambiguous or
+ * surprising directive name. Underscore is the composition separator
+ * (`ana_timeline`) and is deliberately NOT accepted inside the namespace or
+ * local-name segments themselves, which is exactly what makes the composed
+ * name's single underscore mark the boundary unambiguously.
  */
 /** The reserved bundle directory names a pack namespace must never collide with (spec.md §1, §8). */
 export const RESERVED_NAMESPACE_SEGMENTS = new Set([
@@ -116,15 +119,30 @@ export function validateLocalComponentName(name) {
 }
 /**
  * Composes the directive name an author types to reference a pack's
- * component, e.g. `composeDirectiveName('ana', 'timeline')` -> `ana-timeline`
+ * component, e.g. `composeDirectiveName('ana', 'timeline')` -> `ana_timeline`
  * (docs/packs.md). Validates both inputs first, then the composed result
  * (defense in depth: the composed string must still contain no `:` and must
  * still be a legal directive-name shape).
  *
- * `separator` defaults to `-`; `_` is also accepted per spec.md §1's "joins
- * the namespace and name with `-` or `_`".
+ * The separator is `_`, and there is deliberately no way to ask for another
+ * one (issue #19, user-settled 2026-08-30). It used to be `-`, which is also
+ * the separator INSIDE a lowercase-kebab pack or local name, so two
+ * different packs could compose the same directive name: pack `long` plus
+ * component `pack-name-some-component` and pack `long-pack-name` plus
+ * component `some-component` both produced `long-pack-name-some-component`,
+ * and one silently shadowed the other. `SEGMENT_RE` bans `_` inside either
+ * segment, so an underscore join gives every composed name exactly one
+ * underscore, at the pack/component boundary. That makes the split
+ * bijective and this whole collision class impossible to construct rather
+ * than merely detected.
+ *
+ * Accepting both forms would have kept the ambiguity alive, so only this one
+ * exists. Notes and packs written against the old `-` composition stop
+ * resolving and render the labeled unknown-component fallback; that breakage
+ * was weighed and accepted pre-1.0 rather than carrying a migration shim.
  */
-export function composeDirectiveName(packName, localName, separator = '-') {
+export function composeDirectiveName(packName, localName) {
+    const separator = '_';
     const packResult = validatePackName(packName);
     if (!packResult.ok)
         return packResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/pack",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Component pack contract for Markii (docs/packs.md): the pack.json manifest shape, namespace and engine rules, and hand-rolled validation. No React, no parsing, no bundle loading.",
   "keywords": [
     "markdown",