@mohasinac/appkit 4.57.0 → 4.59.0

package/dist/constants/seed-meta.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Seed/test PROVENANCE METADATA — the vocabulary, not the data.
+ *
+ * ── 🛑 WHY THIS IS IN `constants/` AND NOT IN `seed/` ─────────────────────
+ *
+ * `appkit/src/seed/` is **61% of this package's source bytes and 60% of the
+ * published dist** — 540 files and 24.6 MB of pure fixture data that no
+ * runtime code reads. It is being extracted into its own package so a purge,
+ * a seed or a reseed stops requiring an appkit release, and so Turbopack stops
+ * tracing a graph through 24 MB of object literals.
+ *
+ * Two things stood in the way, and both were in `seed/` by accident of
+ * history rather than by nature:
+ *
+ *   · `TEST_DATA_TTL_DAYS` / `testDataExpiresAt()` — a job handler re-exports
+ *     them, so the SWEEP that reclaims expired fixtures depended on the
+ *     fixture data shipping alongside it.
+ *   · `SeedPurpose` — `BaseDocument` carries the field, so the base type of
+ *     every document in the system pointed into the seed directory.
+ *
+ * Neither is data. A TTL and a three-value union are metadata ABOUT seeding
+ * that runtime code legitimately reads, so they live with the other shared
+ * constants and `seed/` keeps only rows.
+ *
+ * 🛑 What deliberately did NOT move: `SEED_COLLECTION_PURPOSE`,
+ * `SEED_ROW_PURPOSE` and `SEED_PURPOSE_DERIVED_FROM`. Those name specific
+ * collections and specific seeded ids — they are registries over the data, so
+ * they belong with it, and only `appkit-seed` and `audit-seed-purpose` read
+ * them.
+ */
+/**
+ * The TTL stamp every disposable test fixture must carry.
+ *
+ * 🛑 `isTestData: true` WITHOUT `testDataExpiresAt` means PERMANENT — nothing
+ * ever reclaims it (see `jobs/handlers/_helpers.ts`, which documents the same
+ * rule from the sweep's side). That is not a theoretical hazard: until
+ * 2026-10-10 the only two `isTestData` rows in the whole seed,
+ * `product-tester-crossstore-a` / `-b`, were in exactly that state — live in
+ * the public catalogue of 72 products, never purged, and one of them was
+ * `store-letitrip-official`'s ONLY buyable standard product, so it was hidden
+ * from every real buyer by `hidePublicTestData` while being the only thing
+ * that store had to sell. Both are deleted.
+ *
+ * And the reason they were permanent is that **this module had zero callers**.
+ * The helper that enforces the rule existed, was documented as the rule that
+ * matters most, and no fixture used it. So: a fixture's three obligations are
+ * an id containing `-test-`, `isTestData: true`, and an expiry FROM HERE.
+ *
+ * Recomputed fresh on every seed run (seed files are re-imported per
+ * invocation), so re-seeding naturally refreshes the expiry rather than
+ * leaving a fixture that expired between runs.
+ *
+ * 🛑 Do NOT re-declare the day count elsewhere. It used to be declared twice —
+ * in the seed directory and in `jobs/handlers/messages.ts` — with a comment as
+ * the only thing keeping them equal, which is the drift shape Root Cause #42
+ * describes. `messages.ts` re-exports this one.
+ */
+export declare const TEST_DATA_TTL_DAYS = 7;
+export declare function testDataExpiresAt(): Date;
+/**
+ * Why a seeded row exists — i.e. what a purge is allowed to do with it.
+ *
+ * 🛑 Not a severity scale. Two different answers to one question: never, and
+ * on request.
+ */
+export type SeedPurpose = 
+/**
+ * Clearable test data. **The default**, and what almost everything is.
+ *
+ * Users, stores, listings, auctions, orders, bids, reviews, offers, carts,
+ * payouts — everything seeded to exercise a path rather than to be read as
+ * content. `appkit-seed purge` removes these and nothing else.
+ *
+ * 🛑 `test` says nothing about PUBLIC VISIBILITY. A demo product is `test`
+ * and fully visible; that is what makes the demo a demo. Hiding a row from
+ * the public is `isTestData`, which is a separate decision.
+ */
+"test"
+/**
+ * Real content. **A purge must NEVER remove it**, because re-creating it is
+ * not a re-seed, it is authoring.
+ *
+ * The test to apply: *if clearing this means somebody has to WRITE it again
+ * rather than re-run a loader, it is permanent.*
+ *
+ * That is why the **tester checklist cases** are in here and not in some
+ * harness tier — they are the real catalogue of issues the testers test
+ * against and keep updating, which is authored content that happens to be
+ * about testing. Its 1,500-odd cases are no more disposable than the 85 FAQs.
+ */
+ | "permanent";
+/**
+ * `Record<SeedPurpose, true>`, so a third value is a compile error in every map
+ * keyed on the union rather than a silent gap (Root Cause #61).
+ */
+export declare const SEED_PURPOSE_VALUES: Record<SeedPurpose, true>;
+export declare const ALL_SEED_PURPOSES: SeedPurpose[];
+export declare function isSeedPurpose(value: unknown): value is SeedPurpose;
+/**
+ * 🛑 There is deliberately NO third `fixture` tier.
+ *
+ * An earlier draft had one, meaning "clearable but only by an explicit full
+ * purge", intended for the tester checklist. Once the cases were correctly
+ * classified as permanent content it had **nothing in it** — and a union member
+ * with no members is the dead-enum-value shape this codebase keeps paying for:
+ * a filter chip whose value no row carries returns zero rows forever and reads
+ * as a working control (Root Cause #33), and nine section types that exist in a
+ * dropdown and have never rendered.
+ *
+ * Two values answer the question that was actually asked. If a genuine third
+ * case appears, add it then — with a row that needs it.
+ */
+export declare const PURGEABLE: Record<SeedPurpose, boolean>;

package/dist/constants/seed-meta.js

@@ -0,0 +1,91 @@
+/**
+ * Seed/test PROVENANCE METADATA — the vocabulary, not the data.
+ *
+ * ── 🛑 WHY THIS IS IN `constants/` AND NOT IN `seed/` ─────────────────────
+ *
+ * `appkit/src/seed/` is **61% of this package's source bytes and 60% of the
+ * published dist** — 540 files and 24.6 MB of pure fixture data that no
+ * runtime code reads. It is being extracted into its own package so a purge,
+ * a seed or a reseed stops requiring an appkit release, and so Turbopack stops
+ * tracing a graph through 24 MB of object literals.
+ *
+ * Two things stood in the way, and both were in `seed/` by accident of
+ * history rather than by nature:
+ *
+ *   · `TEST_DATA_TTL_DAYS` / `testDataExpiresAt()` — a job handler re-exports
+ *     them, so the SWEEP that reclaims expired fixtures depended on the
+ *     fixture data shipping alongside it.
+ *   · `SeedPurpose` — `BaseDocument` carries the field, so the base type of
+ *     every document in the system pointed into the seed directory.
+ *
+ * Neither is data. A TTL and a three-value union are metadata ABOUT seeding
+ * that runtime code legitimately reads, so they live with the other shared
+ * constants and `seed/` keeps only rows.
+ *
+ * 🛑 What deliberately did NOT move: `SEED_COLLECTION_PURPOSE`,
+ * `SEED_ROW_PURPOSE` and `SEED_PURPOSE_DERIVED_FROM`. Those name specific
+ * collections and specific seeded ids — they are registries over the data, so
+ * they belong with it, and only `appkit-seed` and `audit-seed-purpose` read
+ * them.
+ */
+/**
+ * The TTL stamp every disposable test fixture must carry.
+ *
+ * 🛑 `isTestData: true` WITHOUT `testDataExpiresAt` means PERMANENT — nothing
+ * ever reclaims it (see `jobs/handlers/_helpers.ts`, which documents the same
+ * rule from the sweep's side). That is not a theoretical hazard: until
+ * 2026-10-10 the only two `isTestData` rows in the whole seed,
+ * `product-tester-crossstore-a` / `-b`, were in exactly that state — live in
+ * the public catalogue of 72 products, never purged, and one of them was
+ * `store-letitrip-official`'s ONLY buyable standard product, so it was hidden
+ * from every real buyer by `hidePublicTestData` while being the only thing
+ * that store had to sell. Both are deleted.
+ *
+ * And the reason they were permanent is that **this module had zero callers**.
+ * The helper that enforces the rule existed, was documented as the rule that
+ * matters most, and no fixture used it. So: a fixture's three obligations are
+ * an id containing `-test-`, `isTestData: true`, and an expiry FROM HERE.
+ *
+ * Recomputed fresh on every seed run (seed files are re-imported per
+ * invocation), so re-seeding naturally refreshes the expiry rather than
+ * leaving a fixture that expired between runs.
+ *
+ * 🛑 Do NOT re-declare the day count elsewhere. It used to be declared twice —
+ * in the seed directory and in `jobs/handlers/messages.ts` — with a comment as
+ * the only thing keeping them equal, which is the drift shape Root Cause #42
+ * describes. `messages.ts` re-exports this one.
+ */
+export const TEST_DATA_TTL_DAYS = 7;
+export function testDataExpiresAt() {
+    return new Date(Date.now() + TEST_DATA_TTL_DAYS * 24 * 60 * 60 * 1000);
+}
+/**
+ * `Record<SeedPurpose, true>`, so a third value is a compile error in every map
+ * keyed on the union rather than a silent gap (Root Cause #61).
+ */
+export const SEED_PURPOSE_VALUES = {
+    test: true,
+    permanent: true,
+};
+export const ALL_SEED_PURPOSES = Object.keys(SEED_PURPOSE_VALUES);
+export function isSeedPurpose(value) {
+    return typeof value === "string" && value in SEED_PURPOSE_VALUES;
+}
+/**
+ * 🛑 There is deliberately NO third `fixture` tier.
+ *
+ * An earlier draft had one, meaning "clearable but only by an explicit full
+ * purge", intended for the tester checklist. Once the cases were correctly
+ * classified as permanent content it had **nothing in it** — and a union member
+ * with no members is the dead-enum-value shape this codebase keeps paying for:
+ * a filter chip whose value no row carries returns zero rows forever and reads
+ * as a working control (Root Cause #33), and nine section types that exist in a
+ * dropdown and have never rendered.
+ *
+ * Two values answer the question that was actually asked. If a genuine third
+ * case appears, add it then — with a row that needs it.
+ */
+export const PURGEABLE = {
+    test: true,
+    permanent: false,
+};

package/dist/features/admin/components/AdminBeysView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AdminBeysView — browse and correct the generated Beyblade database.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `beys` is 1,988 rows built by committed generators from a crawled corpus. So
+ * there is no "Add Beyblade" button: a row authored here would have no source,
+ * would vanish on the next regeneration, and would make the claim "this dataset
+ * rebuilds from `appkit/src/seed/` alone" false. Adding one is a change to the
+ * generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:beys
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/beys/page.tsx
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminBeysViewProps = ListingLayoutProps;
+export declare function AdminBeysView({ children, ...props }: AdminBeysViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminBeysView.js

@@ -0,0 +1,178 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminBeysView — browse and correct the generated Beyblade database.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `beys` is 1,988 rows built by committed generators from a crawled corpus. So
+ * there is no "Add Beyblade" button: a row authored here would have no source,
+ * would vanish on the next regeneration, and would make the claim "this dataset
+ * rebuilds from `appkit/src/seed/` alone" false. Adding one is a change to the
+ * generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:beys
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/beys/page.tsx
+ */
+import React from "react";
+import { Heading, ListingLayout, Stack, Text } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { BEY_FIELDS } from "../../../constants/field-names.js";
+import { sortBy } from "../../../constants/sort.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DataListingView } from "./DataListingView.js";
+/**
+ * 🛑 Rows are read from WHICHEVER envelope shape arrives.
+ *
+ * `apiClient.get()` unwraps `{success, data}` and returns `data` itself, so an
+ * endpoint that puts rows directly in `data` hands `mapRows` an ARRAY while one
+ * that nests them hands it an object. Reading `.data` off an array yields
+ * undefined — which is exactly how the categories listing rendered "No
+ * categories found" against a 200 carrying 58 rows. This route returns the
+ * object shape, and tolerating both is what keeps that from mattering.
+ */
+function extractRows(response) {
+    if (Array.isArray(response))
+        return response;
+    if (!response || typeof response !== "object")
+        return [];
+    const obj = response;
+    if (Array.isArray(obj.data))
+        return obj.data;
+    return Array.isArray(obj.items) ? obj.items : [];
+}
+function extractTotal(response) {
+    if (Array.isArray(response) || !response || typeof response !== "object")
+        return undefined;
+    const total = response.total;
+    return typeof total === "number" ? total : undefined;
+}
+/*
+ * audit-create-affordance-ok: this listing is deliberately inbound-only.
+ * The 1,988 rows are produced by committed generators from a crawled
+ * corpus, so there is no POST endpoint and no create route key to point a
+ * button at — a Beyblade authored by hand would have no source, would vanish
+ * on the next regeneration, and would make "this dataset rebuilds from
+ * appkit/src/seed/ alone" false. Adding one is a change to the generator.
+ * The surface exists to CORRECT a wrong extraction and to REMOVE a row that
+ * should not exist, which are the two operations the data actually needs.
+ */
+const COLUMNS = [
+    {
+        key: "primary",
+        header: "Beyblade",
+        sortable: true,
+        render: (row) => (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { weight: "semibold", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", children: row.secondary })] })),
+    },
+    {
+        key: "weight",
+        header: "Mass",
+        className: "w-28",
+        render: (row) => (_jsx(Text, { size: "sm", color: "muted", children: row.weight })),
+    },
+    {
+        key: "edited",
+        header: "Corrected",
+        className: "w-28",
+        /*
+         * 🛑 Shown as a COLUMN, because a hand-corrected row behaves differently
+         * from its neighbours — the generator no longer owns the fields somebody
+         * fixed. Leaving that invisible is how a later maintainer concludes the
+         * generator is producing a value it is actually being prevented from
+         * writing. Text, not a colour-only dot (colour is never the only signal).
+         */
+        render: (row) => row.edited ? (_jsx(Text, { size: "xs", weight: "medium", children: "By hand" })) : (_jsx(Text, { size: "xs", color: "faint", children: "Generated" })),
+    },
+];
+const ADMIN_BEYS_CONFIG = {
+    portal: "admin",
+    title: "Beyblades",
+    subtitle: "The generated Beyblade database. Corrections made here are kept when the database is regenerated.",
+    searchPlaceholder: "Search Beyblades by name — Dranzer F, Variares…",
+    /*
+     * 🛑 `searchCommit: "enter"`, not debounce. The route's search is an indexed
+     * PREFIX range, so a partial word is a different query rather than a
+     * narrowing one — debouncing would fire a range query per pause and show
+     * confusing intermediate results. Enter also makes the prefix-only behaviour
+     * legible: you typed a prefix and asked for it.
+     */
+    searchCommit: "enter",
+    /*
+     * 🛑 DECLARED, so the placeholder can be CHECKED rather than trusted.
+     * The route matches exactly one field — an indexed prefix range on
+     * `name` — and the placeholder must not imply more. It is a prefix and
+     * it is case-sensitive; `mode` says so where a reader will see it.
+     */
+    search: {
+        placeholder: "Search Beyblades by name — a prefix, case-sensitive",
+        fields: ["name"],
+    },
+    emptyLabel: "No Beyblade matches that name",
+    filterKeys: [],
+    /*
+     * 🛑 Through `sortBy`, not a bare "name". The route currently ALWAYS
+     * orders by name and ignores the `sorts` param, so this is the only
+     * option — but writing it as a literal is what lets a field rename
+     * leave a sort string that silently sorts nothing.
+     */
+    defaultSort: sortBy(BEY_FIELDS.NAME, "ASC"),
+    pageSize: 25,
+    queryKey: ["admin", "beys"],
+    endpoint: ADMIN_ENDPOINTS.BEYS,
+    sortOptions: [{ value: sortBy(BEY_FIELDS.NAME, "ASC"), label: "Name A-Z" }],
+    columns: COLUMNS,
+    buildFilters: () => undefined,
+    getTotal: (response, rows) => extractTotal(response) ?? rows.length,
+    mapRows: (response) => extractRows(response).map((raw) => {
+        const r = raw;
+        /*
+         * 🛑 `≈` when the mass was SUMMED from the parts rather than stated by
+         * the source. 93% of beys have a mass but only 248 state it, and a
+         * derived figure shown as an exact one is the easiest way for this
+         * dataset to start lying — the same marking the detail page and the OG
+         * card use.
+         */
+        const summed = typeof r.weightGFromParts === "number" ? r.weightGFromParts : null;
+        const weight = typeof r.weightG === "number"
+            ? `${r.weightG} g`
+            : summed !== null
+                ? `≈ ${Math.round(summed * 10) / 10} g`
+                : "—";
+        return {
+            id: String(r.id ?? ""),
+            primary: String(r.name ?? r.id ?? "Unnamed Beyblade"),
+            /*
+             * System first: it is the one line a collector uses to place a bey in
+             * time, and it is present on 94% of them. The product code follows
+             * because two vendor releases of one model differ by little else.
+             */
+            secondary: [r.system, Array.isArray(r.productCodes) ? r.productCodes[0] : null]
+                .filter(Boolean)
+                .join(" · ") || "—",
+            weight,
+            edited: r.adminEdited === true,
+        };
+    }),
+    /*
+     * 🛑 `rowHrefTemplate`, not `rowHref`. Verified against the interface
+     * rather than guessed — there is no `rowHref` field, and an unknown key on
+     * an object literal typed by an interface is a compile error I could not
+     * have seen under this session's no-build cap.
+     */
+    rowHrefTemplate: (row) => String(ROUTES.ADMIN.BEYS_EDIT(row.id)),
+};
+export function AdminBeysView({ children, ...props }) {
+    if (React.Children.count(children) > 0) {
+        return (_jsxs(ListingLayout, { portal: "admin", ...props, children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Beyblades" }), children] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Beyblades" }), _jsx(DataListingView, { config: ADMIN_BEYS_CONFIG })] }));
+}

package/dist/features/admin/components/AdminPartsView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AdminPartsView — browse and correct the generated part glossary.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `partGlossary` is 2,488 rows built by committed generators from a crawled
+ * corpus. So there is no "Add part" button: a row authored here would have no
+ * source, would vanish on the next regeneration, and would make the claim
+ * "this dataset rebuilds from `appkit/src/seed/` alone" false. Adding a part is
+ * a change to the generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:parts
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/parts/page.tsx
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminPartsViewProps = ListingLayoutProps;
+export declare function AdminPartsView({ children, ...props }: AdminPartsViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminPartsView.js

@@ -0,0 +1,160 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminPartsView — browse and correct the generated part glossary.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `partGlossary` is 2,488 rows built by committed generators from a crawled
+ * corpus. So there is no "Add part" button: a row authored here would have no
+ * source, would vanish on the next regeneration, and would make the claim
+ * "this dataset rebuilds from `appkit/src/seed/` alone" false. Adding a part is
+ * a change to the generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:parts
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/parts/page.tsx
+ */
+import React from "react";
+import { Heading, ListingLayout, Stack, Text } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { PART_GLOSSARY_FIELDS } from "../../../constants/field-names.js";
+import { sortBy } from "../../../constants/sort.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DataListingView } from "./DataListingView.js";
+/**
+ * 🛑 Rows are read from WHICHEVER envelope shape arrives.
+ *
+ * `apiClient.get()` unwraps `{success, data}` and returns `data` itself, so an
+ * endpoint that puts rows directly in `data` hands `mapRows` an ARRAY while one
+ * that nests them hands it an object. Reading `.data` off an array yields
+ * undefined — which is exactly how the categories listing rendered "No
+ * categories found" against a 200 carrying 58 rows. This route returns the
+ * object shape, and tolerating both is what keeps that from mattering.
+ */
+function extractRows(response) {
+    if (Array.isArray(response))
+        return response;
+    if (!response || typeof response !== "object")
+        return [];
+    const obj = response;
+    if (Array.isArray(obj.data))
+        return obj.data;
+    return Array.isArray(obj.items) ? obj.items : [];
+}
+function extractTotal(response) {
+    if (Array.isArray(response) || !response || typeof response !== "object")
+        return undefined;
+    const total = response.total;
+    return typeof total === "number" ? total : undefined;
+}
+/*
+ * audit-create-affordance-ok: this listing is deliberately inbound-only.
+ * The 2,488 rows are produced by committed generators from a crawled
+ * corpus, so there is no POST endpoint and no create route key to point a
+ * button at — a part authored by hand would have no source, would vanish
+ * on the next regeneration, and would make "this dataset rebuilds from
+ * appkit/src/seed/ alone" false. Adding one is a change to the generator.
+ * The surface exists to CORRECT a wrong extraction and to REMOVE a row that
+ * should not exist, which are the two operations the data actually needs.
+ */
+const COLUMNS = [
+    {
+        key: "primary",
+        header: "Part",
+        sortable: true,
+        render: (row) => (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { weight: "semibold", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", children: row.secondary })] })),
+    },
+    {
+        key: "weight",
+        header: "Weight",
+        className: "w-24",
+        render: (row) => (_jsx(Text, { size: "sm", color: "muted", children: row.weight })),
+    },
+    {
+        key: "edited",
+        header: "Corrected",
+        className: "w-28",
+        /*
+         * 🛑 Shown as a COLUMN, because a hand-corrected row behaves differently
+         * from its neighbours — the generator no longer owns the fields somebody
+         * fixed. Leaving that invisible is how a later maintainer concludes the
+         * generator is producing a value it is actually being prevented from
+         * writing. Text, not a colour-only dot (colour is never the only signal).
+         */
+        render: (row) => row.edited ? (_jsx(Text, { size: "xs", weight: "medium", children: "By hand" })) : (_jsx(Text, { size: "xs", color: "faint", children: "Generated" })),
+    },
+];
+const ADMIN_PARTS_CONFIG = {
+    portal: "admin",
+    title: "Parts",
+    subtitle: "The generated part glossary. Corrections made here are kept when the database is regenerated.",
+    searchPlaceholder: "Search parts by name — Rubber Flat, Dranzer…",
+    /*
+     * 🛑 `searchCommit: "enter"`, not debounce. The route's search is an indexed
+     * PREFIX range, so a partial word is a different query rather than a
+     * narrowing one — debouncing would fire a range query per pause and show
+     * confusing intermediate results. Enter also makes the prefix-only behaviour
+     * legible: you typed a prefix and asked for it.
+     */
+    searchCommit: "enter",
+    /*
+     * 🛑 DECLARED, so the placeholder can be CHECKED rather than trusted.
+     * The route matches exactly one field — an indexed prefix range on
+     * `name` — and the placeholder must not imply more. It is a prefix and
+     * it is case-sensitive; `mode` says so where a reader will see it.
+     */
+    search: {
+        placeholder: "Search parts by name — a prefix, case-sensitive",
+        fields: ["name"],
+    },
+    emptyLabel: "No part matches that name",
+    filterKeys: [],
+    /*
+     * 🛑 Through `sortBy`, not a bare "name". The route currently ALWAYS
+     * orders by name and ignores the `sorts` param, so this is the only
+     * option — but writing it as a literal is what lets a field rename
+     * leave a sort string that silently sorts nothing.
+     */
+    defaultSort: sortBy(PART_GLOSSARY_FIELDS.NAME, "ASC"),
+    pageSize: 25,
+    queryKey: ["admin", "parts"],
+    endpoint: ADMIN_ENDPOINTS.PARTS,
+    sortOptions: [{ value: sortBy(PART_GLOSSARY_FIELDS.NAME, "ASC"), label: "Name A-Z" }],
+    columns: COLUMNS,
+    buildFilters: () => undefined,
+    getTotal: (response, rows) => extractTotal(response) ?? rows.length,
+    mapRows: (response) => extractRows(response).map((raw) => {
+        const r = raw;
+        const weight = typeof r.weightG === "number" ? `${r.weightG} g` : "—";
+        return {
+            id: String(r.id ?? ""),
+            primary: String(r.name ?? r.id ?? "Unnamed part"),
+            /* The classification is what disambiguates a bare code like "105". */
+            secondary: [r.classification, r.code].filter(Boolean).join(" · ") || "—",
+            weight,
+            edited: r.adminEdited === true,
+        };
+    }),
+    /*
+     * 🛑 `rowHrefTemplate`, not `rowHref`. Verified against the interface
+     * rather than guessed — there is no `rowHref` field, and an unknown key on
+     * an object literal typed by an interface is a compile error I could not
+     * have seen under this session's no-build cap.
+     */
+    rowHrefTemplate: (row) => String(ROUTES.ADMIN.PARTS_EDIT(row.id)),
+};
+export function AdminPartsView({ children, ...props }) {
+    if (React.Children.count(children) > 0) {
+        return (_jsxs(ListingLayout, { portal: "admin", ...props, children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), children] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), _jsx(DataListingView, { config: ADMIN_PARTS_CONFIG })] }));
+}

package/dist/features/admin/components/OwnerQuickActions.d.ts

@@ -1,5 +1,5 @@
 /** Which registry bucket supplies the labels and the confirm copy. */
-export type OwnerQuickActionsResource = "PRODUCT" | "CATEGORY" | "BRAND" | "FRANCHISE" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW" | "STORE" | "USER" | "CAROUSEL" | "SECTION";
+export type OwnerQuickActionsResource = "PRODUCT" | "CATEGORY" | "BRAND" | "FRANCHISE" | "PART" | "BEY" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW" | "STORE" | "USER" | "CAROUSEL" | "SECTION";
 export interface OwnerQuickActionsProps {
     resource: OwnerQuickActionsResource;
     /** Where the pencil goes — that record's dashboard editor. */
@@ -24,6 +24,23 @@ export interface OwnerQuickActionsProps {
      * `detail` sits in a header row beside the title.
      */
     placement?: "card" | "detail";
+    /**
+     * 🛑 Set this whenever `placement="detail"` sits on a DARK cover hero.
+     *
+     * `detail` otherwise renders the `ghost` variant, which is
+     * `color: var(--appkit-color-zinc-600)` — a dark grey that is correct on a
+     * page-surface header row and invisible on a cover photo. Every detail view
+     * that has a hero already computes a `hasCover` flag and flips each of its
+     * siblings to `color="inverse"`; this toolbar was the one element in that
+     * block that did not, so the pencil rendered near-black on near-black and
+     * read as "admins get no edit button" (Root Cause #67 — a theme-relative ink
+     * on a theme-invariant dark surface).
+     *
+     * Pass the SAME flag the rest of the hero branches on, not a literal `true`:
+     * a coverless hero falls back to the page surface, where the scrim's white
+     * ink would be invisible in the mirror-image way.
+     */
+    onMedia?: boolean;
     className?: string;
 }
-export declare function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement, className, }: OwnerQuickActionsProps): import("react").JSX.Element | null;
+export declare function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement, onMedia, className, }: OwnerQuickActionsProps): import("react").JSX.Element | null;