@markii/pack 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @markii/pack
+
+Component pack contract for [Markii](https://github.com/sadigaxund/markii): the `pack.json` manifest shape (`docs/packs.md`), namespace and engine rules, and hand-rolled validation. No React, no markdown parsing, no bundle loading — this package defines the contract that a later registry-loading slice builds against.
+
+See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { PackManifest, PackManifestParseResult } from './manifest.js';
+export { parsePackManifest } from './manifest.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';
+export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+// @markii/pack: the neutral component-pack contract (docs/packs.md). This
+// is slice 0 of issue #3 — the manifest shape, namespace/engine rules, and
+// 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 { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
+export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/manifest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `pack.json`'s contract (docs/packs.md). Three fields, all required:
+ *
+ *   { "name": "ana", "engine": "react",
+ *     "components": { "timeline": "./Timeline.tsx" } }
+ *
+ * `name` is the pack's namespace (see `./namespace.ts`). `engine` names the
+ * 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.
+ *
+ * Shared Lua modules are NOT a manifest field. docs/packs.md says they
+ * travel under a conventional `scripts/` directory inside the pack
+ * (`require "ana/http"`), the same way a bundle's `scripts/` works — there
+ * is no separate manifest declaration for them, so this type doesn't add
+ * one. (Flagged in the slice-0 report for orchestrator sign-off in case
+ * docs/packs.md meant something more explicit.)
+ */
+export interface PackManifest {
+    /** The pack's namespace, e.g. `"ana"`. See `validatePackName`. */
+    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>;
+}
+export type PackManifestParseResult = {
+    ok: true;
+    manifest: PackManifest;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Hand-rolled `pack.json` validation (no schema library — see AGENTS.md
+ * dependency policy), mirroring `@markii/bundle`'s `parseManifest` style:
+ * never throws, malformed JSON or a non-object root comes back as
+ * `{ ok: false, errors }`, and unrecognized top-level keys are
+ * forward-compatible warnings rather than errors.
+ *
+ * Reads the `components` map with `Object.hasOwn` only — never a `for...in`
+ * or bare property access — so a hostile manifest cannot use inherited
+ * properties (`{}.toString`, etc.) to inject a component entry, and a key
+ * literally named `__proto__`/`constructor`/`prototype` is validated (and
+ * rejected — see `validateLocalComponentName`'s charset) like any other
+ * string key, never treated as a prototype-chain write.
+ */
+export declare function parsePackManifest(json: string): PackManifestParseResult;

package/dist/manifest.js

@@ -0,0 +1,123 @@
+import { validateLocalComponentName, validatePackName } from './namespace.js';
+const KNOWN_TOP_LEVEL_KEYS = new Set(['name', 'engine', 'components']);
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Hand-rolled `pack.json` validation (no schema library — see AGENTS.md
+ * dependency policy), mirroring `@markii/bundle`'s `parseManifest` style:
+ * never throws, malformed JSON or a non-object root comes back as
+ * `{ ok: false, errors }`, and unrecognized top-level keys are
+ * forward-compatible warnings rather than errors.
+ *
+ * Reads the `components` map with `Object.hasOwn` only — never a `for...in`
+ * or bare property access — so a hostile manifest cannot use inherited
+ * properties (`{}.toString`, etc.) to inject a component entry, and a key
+ * literally named `__proto__`/`constructor`/`prototype` is validated (and
+ * rejected — see `validateLocalComponentName`'s charset) like any other
+ * string key, never treated as a prototype-chain write.
+ */
+export function parsePackManifest(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errors: [
+                `malformed JSON: ${err instanceof Error ? err.message : String(err)}`,
+            ],
+        };
+    }
+    if (!isPlainObject(raw)) {
+        return { ok: false, errors: ['pack manifest must be a JSON object'] };
+    }
+    const obj = raw;
+    const errors = [];
+    const warnings = [];
+    // --- name (required) ---
+    let name;
+    if (!Object.hasOwn(obj, 'name')) {
+        errors.push('"name" is required');
+    }
+    else {
+        const nameResult = validatePackName(obj.name);
+        if (!nameResult.ok) {
+            errors.push(`"name": ${nameResult.reason}`);
+        }
+        else {
+            name = obj.name;
+        }
+    }
+    // --- engine (required) ---
+    let engine;
+    if (!Object.hasOwn(obj, 'engine')) {
+        errors.push('"engine" is required');
+    }
+    else if (typeof obj.engine !== 'string' || obj.engine.length === 0) {
+        errors.push('"engine" must be a non-empty string');
+    }
+    else {
+        engine = obj.engine;
+    }
+    // --- components (required) ---
+    let components;
+    if (!Object.hasOwn(obj, 'components')) {
+        errors.push('"components" is required');
+    }
+    else if (!isPlainObject(obj.components)) {
+        errors.push('"components" must be an object');
+    }
+    else {
+        const componentsObj = obj.components;
+        const result = {};
+        let componentsValid = true;
+        for (const key of Object.keys(componentsObj)) {
+            if (!Object.hasOwn(componentsObj, key))
+                continue;
+            const localNameResult = validateLocalComponentName(key);
+            if (!localNameResult.ok) {
+                errors.push(`"components" key "${key}": ${localNameResult.reason}`);
+                componentsValid = false;
+                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)`);
+                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;
+        }
+        if (Object.keys(componentsObj).length === 0) {
+            errors.push('"components" must have at least one entry');
+            componentsValid = false;
+        }
+        if (componentsValid) {
+            components = result;
+        }
+    }
+    // --- unknown top-level keys: forward-compat warning, not an error ---
+    for (const key of Object.keys(obj)) {
+        if (Object.hasOwn(obj, key) && !KNOWN_TOP_LEVEL_KEYS.has(key)) {
+            warnings.push(`unknown pack manifest key "${key}" (ignored by this implementation)`);
+        }
+    }
+    if (errors.length > 0 ||
+        name === undefined ||
+        engine === undefined ||
+        components === undefined) {
+        return { ok: false, errors };
+    }
+    return {
+        ok: true,
+        manifest: { name, engine, components },
+        warnings,
+    };
+}

package/dist/namespace.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Namespace rules from docs/packs.md and spec.md §1:
+ *
+ * - Directive names MUST NOT contain `:` (reserved syntax).
+ * - A namespaced directive name joins the pack's namespace and the
+ *   component's local name with `-` or `_`.
+ * - 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.
+ *
+ * This module is pure and dependency-free, mirroring `@markii/bundle`'s
+ * `paths.ts`: no filesystem, no registry, just the string rules a later
+ * slice (registry loading, install-time rejection) builds on.
+ *
+ * Design decision (orchestrator sign-off requested — see the slice-0
+ * report): the charset chosen for both a pack namespace and a pack's local
+ * component names is lowercase-kebab, matching spec.md §1's "SHOULD be
+ * lowercase-kebab" guidance for directive names generally: a leading
+ * lowercase letter, then lowercase letters/digits, with single internal
+ * 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.
+ */
+/** The reserved bundle directory names a pack namespace must never collide with (spec.md §1, §8). */
+export declare const RESERVED_NAMESPACE_SEGMENTS: ReadonlySet<string>;
+export type NamespaceValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a pack name (the pack's namespace). Never throws.
+ *
+ * Rejects: non-strings, empty strings, anything outside the lowercase-kebab
+ * charset (this also rejects `:` and any prototype-pollution-shaped name
+ * such as `__proto__` or `constructor`, since neither matches the charset),
+ * and the reserved bundle segments `scripts`, `assets`, `.cache`.
+ */
+export declare function validatePackName(name: unknown): NamespaceValidationResult;
+/**
+ * Validates a pack's local component name (the key on the manifest's
+ * `components` map, before namespacing). Same lowercase-kebab charset as a
+ * pack name; this also rejects prototype-pollution-shaped keys.
+ */
+export declare function validateLocalComponentName(name: unknown): NamespaceValidationResult;
+export type ComposeDirectiveNameResult = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Composes the directive name an author types to reference a pack's
+ * 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 `_`".
+ */
+export declare function composeDirectiveName(packName: string, localName: string, separator?: '-' | '_'): ComposeDirectiveNameResult;
+export interface NamespaceCollision {
+    namespace: string;
+    /** How many times this namespace appears in the input. */
+    count: number;
+}
+/**
+ * Given several installed pack namespaces, returns the ones that appear
+ * more than once. Pure predicate only — docs/packs.md says installing two
+ * packs with the same namespace is rejected at install time, but that
+ * install-time rejection (and the vault-library-shadows-a-pack warning
+ * case) is a later slice; this is the detection primitive it will use.
+ *
+ * Comparison is exact-string (case-sensitive), matching `validatePackName`
+ * which already forces lowercase, so two namespaces differing only in case
+ * cannot arise from valid input in the first place.
+ */
+export declare function detectNamespaceCollisions(namespaces: readonly string[]): NamespaceCollision[];

package/dist/namespace.js

@@ -0,0 +1,176 @@
+/**
+ * Namespace rules from docs/packs.md and spec.md §1:
+ *
+ * - Directive names MUST NOT contain `:` (reserved syntax).
+ * - A namespaced directive name joins the pack's namespace and the
+ *   component's local name with `-` or `_`.
+ * - 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.
+ *
+ * This module is pure and dependency-free, mirroring `@markii/bundle`'s
+ * `paths.ts`: no filesystem, no registry, just the string rules a later
+ * slice (registry loading, install-time rejection) builds on.
+ *
+ * Design decision (orchestrator sign-off requested — see the slice-0
+ * report): the charset chosen for both a pack namespace and a pack's local
+ * component names is lowercase-kebab, matching spec.md §1's "SHOULD be
+ * lowercase-kebab" guidance for directive names generally: a leading
+ * lowercase letter, then lowercase letters/digits, with single internal
+ * 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.
+ */
+/** The reserved bundle directory names a pack namespace must never collide with (spec.md §1, §8). */
+export const RESERVED_NAMESPACE_SEGMENTS = new Set([
+    'scripts',
+    'assets',
+    '.cache',
+]);
+// Lowercase-kebab: starts with a lowercase letter, then lowercase
+// letters/digits, with single internal hyphens. No leading/trailing
+// hyphen, no consecutive hyphens, no underscore, no colon, no uppercase.
+const SEGMENT_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+// Plain object prototype members that would otherwise pass SEGMENT_RE (they
+// are lowercase-kebab-shaped, no ":" or "_"). Rejected by name, defense in
+// depth alongside every reader in this package using Object.hasOwn: a
+// namespace or local name equal to one of these is never a meaningful
+// component name and is exactly the shape a prototype-pollution probe uses.
+const PROTOTYPE_MEMBER_NAMES = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    'hasownproperty',
+    'valueof',
+    'tostring',
+    'isprototypeof',
+]);
+/**
+ * Validates a pack name (the pack's namespace). Never throws.
+ *
+ * Rejects: non-strings, empty strings, anything outside the lowercase-kebab
+ * charset (this also rejects `:` and any prototype-pollution-shaped name
+ * such as `__proto__` or `constructor`, since neither matches the charset),
+ * and the reserved bundle segments `scripts`, `assets`, `.cache`.
+ */
+export function validatePackName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        return { ok: false, reason: 'pack name must be a non-empty string' };
+    }
+    if (name.includes(':')) {
+        return { ok: false, reason: 'pack name must not contain ":"' };
+    }
+    if (RESERVED_NAMESPACE_SEGMENTS.has(name)) {
+        return {
+            ok: false,
+            reason: `"${name}" is a reserved bundle segment and cannot be a pack namespace`,
+        };
+    }
+    if (PROTOTYPE_MEMBER_NAMES.has(name.toLowerCase())) {
+        return {
+            ok: false,
+            reason: `"${name}" is a reserved object-prototype member name and cannot be a pack name`,
+        };
+    }
+    if (!SEGMENT_RE.test(name)) {
+        return {
+            ok: false,
+            reason: 'pack name must be lowercase-kebab: a lowercase letter, then lowercase letters/digits, with single internal hyphens',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Validates a pack's local component name (the key on the manifest's
+ * `components` map, before namespacing). Same lowercase-kebab charset as a
+ * pack name; this also rejects prototype-pollution-shaped keys.
+ */
+export function validateLocalComponentName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        return {
+            ok: false,
+            reason: 'component name must be a non-empty string',
+        };
+    }
+    if (name.includes(':')) {
+        return { ok: false, reason: 'component name must not contain ":"' };
+    }
+    if (PROTOTYPE_MEMBER_NAMES.has(name.toLowerCase())) {
+        return {
+            ok: false,
+            reason: `"${name}" is a reserved object-prototype member name and cannot be a component name`,
+        };
+    }
+    if (!SEGMENT_RE.test(name)) {
+        return {
+            ok: false,
+            reason: 'component name must be lowercase-kebab: a lowercase letter, then lowercase letters/digits, with single internal hyphens',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Composes the directive name an author types to reference a pack's
+ * 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 `_`".
+ */
+export function composeDirectiveName(packName, localName, separator = '-') {
+    const packResult = validatePackName(packName);
+    if (!packResult.ok)
+        return packResult;
+    const localResult = validateLocalComponentName(localName);
+    if (!localResult.ok)
+        return localResult;
+    const composed = `${packName}${separator}${localName}`;
+    if (composed.includes(':')) {
+        return {
+            ok: false,
+            reason: 'composed directive name must not contain ":"',
+        };
+    }
+    // The composed name must still look like a directive name: lowercase
+    // letters/digits/hyphens/underscores only, starting with a letter. This
+    // is deliberately looser than SEGMENT_RE (it allows the separator
+    // character throughout) since the composed string is not itself
+    // re-parsed into namespace/local parts anywhere in this package.
+    if (!/^[a-z][a-z0-9_-]*$/.test(composed)) {
+        return {
+            ok: false,
+            reason: `composed directive name "${composed}" is not a legal directive name`,
+        };
+    }
+    return { ok: true, name: composed };
+}
+/**
+ * Given several installed pack namespaces, returns the ones that appear
+ * more than once. Pure predicate only — docs/packs.md says installing two
+ * packs with the same namespace is rejected at install time, but that
+ * install-time rejection (and the vault-library-shadows-a-pack warning
+ * case) is a later slice; this is the detection primitive it will use.
+ *
+ * Comparison is exact-string (case-sensitive), matching `validatePackName`
+ * which already forces lowercase, so two namespaces differing only in case
+ * cannot arise from valid input in the first place.
+ */
+export function detectNamespaceCollisions(namespaces) {
+    const counts = new Map();
+    for (const ns of namespaces) {
+        counts.set(ns, (counts.get(ns) ?? 0) + 1);
+    }
+    const collisions = [];
+    for (const [namespace, count] of counts) {
+        if (count > 1)
+            collisions.push({ namespace, count });
+    }
+    return collisions;
+}

package/dist/uses.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Resolving a note's `uses:` declaration (docs/packs.md, @markii/core's
+ * `Frontmatter.uses`) against the packs a host actually has installed.
+ *
+ * This is host-facing metadata only: it lets a renderer say "this note uses
+ * pack `ana`, which is not installed" instead of showing an unexplained
+ * fallback box. It does not load, register, or validate components — it
+ * just answers "of the packs this note declared, which ones do I have?".
+ *
+ * Pure and dependency-free, mirroring the rest of this package: no
+ * filesystem, no registry, no host coupling.
+ */
+/**
+ * The result of resolving a note's declared `uses:` list against a host's
+ * installed pack namespaces.
+ *
+ * `declared` is `false` only when the note had no `uses:` at all
+ * (`Frontmatter.uses` was `undefined` — "not declared", as opposed to
+ * `uses: []`, "declared, and it names no packs"). When `declared` is
+ * `false`, `missing` and `satisfied` are both empty: there is nothing to
+ * report either way.
+ *
+ * `missing` and `satisfied` partition the de-duplicated declared list
+ * (order-preserving, first occurrence wins) between namespaces the host
+ * does not have installed and ones it does. A declared name that is not
+ * even a syntactically valid pack namespace (see `validatePackName`) can
+ * never be "installed" under any host, so it is counted as `missing` too —
+ * there is no separate bucket for it. The distinction a host UI might want
+ * to draw ("pack not installed" vs. "that name could never be a pack") is
+ * not this helper's job; a host that wants it can run `validatePackName`
+ * itself over `missing`.
+ */
+export interface UsesResolution {
+    declared: boolean;
+    missing: string[];
+    satisfied: string[];
+}
+/**
+ * Resolves a note's declared `uses:` list against the pack namespaces a
+ * host has installed. Never throws.
+ *
+ * - `declaredUses` is `undefined` when the note declared no `uses:` at all;
+ *   `resolveUses` returns `{ declared: false, missing: [], satisfied: [] }`
+ *   in that case without inspecting `installedNamespaces`.
+ * - `declaredUses: []` ("declared, names no packs") returns
+ *   `{ declared: true, missing: [], satisfied: [] }`.
+ * - `installedNamespaces` is consumed into a `Set` once, so any iterable
+ *   works (an array, another `Set`, a generator) and lookups are O(1)
+ *   regardless of how many packs are installed. A `Set` built from
+ *   attacker-controlled strings (e.g. `"__proto__"`) is a safe lookup
+ *   target: `Set.prototype.has` does not consult the prototype chain the
+ *   way a plain-object property read would, so no `Object.hasOwn` guard is
+ *   needed here (unlike `namespace.ts`'s object-key readers).
+ * - Duplicate names in `declaredUses` are de-duplicated; the first
+ *   occurrence's position is what determines its place in the output
+ *   arrays, so host messaging ("missing: ana, gh") stays stable regardless
+ *   of how many times a note repeats a name.
+ * - Neither input is mutated.
+ */
+export declare function resolveUses(declaredUses: readonly string[] | undefined, installedNamespaces: Iterable<string>): UsesResolution;
+/**
+ * Convenience re-export point for callers that want to flag a declared name
+ * that could never be a valid pack namespace in the first place (distinct
+ * from "valid namespace, just not installed"). `resolveUses` itself does not
+ * draw this distinction — see `UsesResolution`'s docs — so a host that wants
+ * it filters `missing` through this predicate.
+ */
+export declare function isValidPackNameShape(name: string): boolean;

package/dist/uses.js

@@ -0,0 +1,66 @@
+/**
+ * Resolving a note's `uses:` declaration (docs/packs.md, @markii/core's
+ * `Frontmatter.uses`) against the packs a host actually has installed.
+ *
+ * This is host-facing metadata only: it lets a renderer say "this note uses
+ * pack `ana`, which is not installed" instead of showing an unexplained
+ * fallback box. It does not load, register, or validate components — it
+ * just answers "of the packs this note declared, which ones do I have?".
+ *
+ * Pure and dependency-free, mirroring the rest of this package: no
+ * filesystem, no registry, no host coupling.
+ */
+import { validatePackName } from './namespace.js';
+/**
+ * Resolves a note's declared `uses:` list against the pack namespaces a
+ * host has installed. Never throws.
+ *
+ * - `declaredUses` is `undefined` when the note declared no `uses:` at all;
+ *   `resolveUses` returns `{ declared: false, missing: [], satisfied: [] }`
+ *   in that case without inspecting `installedNamespaces`.
+ * - `declaredUses: []` ("declared, names no packs") returns
+ *   `{ declared: true, missing: [], satisfied: [] }`.
+ * - `installedNamespaces` is consumed into a `Set` once, so any iterable
+ *   works (an array, another `Set`, a generator) and lookups are O(1)
+ *   regardless of how many packs are installed. A `Set` built from
+ *   attacker-controlled strings (e.g. `"__proto__"`) is a safe lookup
+ *   target: `Set.prototype.has` does not consult the prototype chain the
+ *   way a plain-object property read would, so no `Object.hasOwn` guard is
+ *   needed here (unlike `namespace.ts`'s object-key readers).
+ * - Duplicate names in `declaredUses` are de-duplicated; the first
+ *   occurrence's position is what determines its place in the output
+ *   arrays, so host messaging ("missing: ana, gh") stays stable regardless
+ *   of how many times a note repeats a name.
+ * - Neither input is mutated.
+ */
+export function resolveUses(declaredUses, installedNamespaces) {
+    if (declaredUses === undefined) {
+        return { declared: false, missing: [], satisfied: [] };
+    }
+    const installed = new Set(installedNamespaces);
+    const seen = new Set();
+    const missing = [];
+    const satisfied = [];
+    for (const name of declaredUses) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (installed.has(name)) {
+            satisfied.push(name);
+        }
+        else {
+            missing.push(name);
+        }
+    }
+    return { declared: true, missing, satisfied };
+}
+/**
+ * Convenience re-export point for callers that want to flag a declared name
+ * that could never be a valid pack namespace in the first place (distinct
+ * from "valid namespace, just not installed"). `resolveUses` itself does not
+ * draw this distinction — see `UsesResolution`'s docs — so a host that wants
+ * it filters `missing` through this predicate.
+ */
+export function isValidPackNameShape(name) {
+    return validatePackName(name).ok;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@markii/pack",
+  "version": "0.7.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",
+    "mark",
+    "mk.md",
+    "pack",
+    "namespace"
+  ],
+  "license": "MIT",
+  "author": "sadigaxund",
+  "homepage": "https://github.com/sadigaxund/markii#readme",
+  "bugs": "https://github.com/sadigaxund/markii/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sadigaxund/markii.git",
+    "directory": "packages/markii-pack"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "build:dist": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "eslint ."
+  }
+}