@jxsuite/studio 10.4.0 → 10.6.0

package/src/canvas/iframe-render.ts

@@ -24,6 +24,7 @@ import {
   setCanvasDelinkCommands,
   setCanvasDelinkPopovers,
   setCanvasViewportTranspose,
+  setDocumentParser,
   setRootMedia,
   setSkipAutoRequests,
   setSkipServerFunctions,
@@ -43,6 +44,17 @@ import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxDocument, JxElement, JxStyle } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
 
+/**
+ * Read a `.jxn` `$ref`, which the editing server answers as its text.
+ *
+ * Loaded when one turns up, because the parser is a third of this entry's size budget and most
+ * canvases never see a `.jxn` reference.
+ */
+async function parseDocumentText(text: string, source: string): Promise<JxDocument> {
+  const { parseJxn } = await import("@jxsuite/schema/jxn");
+  return parseJxn(text, source);
+}
+
 /**
  * The retained render context a full render leaves behind so the surgical patcher can re-render an
  * individual subtree (insert/replace/attr edits) with the SAME scope, doc base, path mapping, and
@@ -1070,6 +1082,7 @@ export async function renderResolvedDocument(opts: {
   const assets = opts.assets ?? null;
   setCanvasAssetResolver(assets ? (value) => resolveAssetRef(value, assets) : null);
   setSkipServerFunctions(opts.mode !== "preview");
+  setDocumentParser(parseDocumentText);
   // Same gate for automatic `$prototype: "Request"` state entries. `buildScope` re-resolves every
   // State entry on each full render, so without this an escalating authoring action (a signals-panel
   // Edit, or Enter inside component-wrapped content) issued an HTTP request per render. Edit/design

package/src/collab/collab-session.ts

@@ -33,7 +33,7 @@ import {
   setTransactObserver,
   transactDoc,
 } from "../tabs/transact";
-import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { isProjectConfigPath } from "../tabs/tab";
 import type { TransactOrigin } from "../tabs/transact";
 import type { TransactionRecord } from "../tabs/patch-ops";
 import type { Tab } from "../tabs/tab";
@@ -672,7 +672,7 @@ const liveTabs = new Set<Tab>();
  */
 export function ensureCollab(tab: Tab): void {
   const platform = maybePlatform();
-  if (!platform?.collab || !tab.documentPath || tab.documentPath === PROJECT_CONFIG_PATH) {
+  if (!platform?.collab || !tab.documentPath || isProjectConfigPath(tab.documentPath)) {
     return;
   }
   const runtime = runtimeFor(tab);

package/src/commands/levels.ts

@@ -180,7 +180,7 @@ export const PANEL_PLACEMENT_MATRIX: Readonly<Record<PanelPlacement, PlacementRu
   },
   "rail/document": {
     admits: ["document"],
-    note: "the rail's lower group — Outline, Data, and Packages with the developer panels on",
+    note: "the rail's lower group — Insert, Outline, Data, and Packages with the developer panels on",
   },
   navigator: {
     admits: ["project", "document"],

package/src/content/entry-commands.ts

@@ -1,6 +1,6 @@
 /**
- * The content-entry verbs: open one where it is written, mark one a draft, and choose whether
- * drafts are listed at all — and {@link createEntry}, the New File tree's route into a collection
+ * The content-entry verbs: open one where it is written, hold one back, and choose whether held
+ * entries are listed at all — and {@link createEntry}, the New File tree's route into a collection
  * folder.
  *
  * Creating an entry from anywhere else is Add new's (`file.new { kind: "entry", collection }`,
@@ -9,10 +9,10 @@
  *
  * Each is a record in its owning module, so the palette row, the assistant's tool, the automation
  * step and (for the two that declare one) the context-menu item are renderings of the same
- * declaration. Two of them are **setters and not toggles** — `content.setDraft {draft}` and
- * `content.setIncludeDrafts {include}` name the state they reach, because "toggle the draft flag"
- * run twice by a script leaves the entry exactly where it started and run once against an unknown
- * default publishes something private.
+ * declaration. Two of them are **setters and not toggles** — `content.setHold {hold}` and
+ * `content.setIncludeHeld {include}` name the state they reach, because "toggle the hold" run twice
+ * by a script leaves the entry exactly where it started and run once against an unknown default
+ * publishes something private.
  */
 
 import {
@@ -33,13 +33,13 @@ import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
 import { serializeJson } from "@jxsuite/schema/json-layout";
 import { invalidateReferenceEntries } from "../ui/form-controls";
-import { reloadDraftAwareGrids } from "../grid/sources/content-source";
-import { setIncludeDrafts } from "./draft-state";
+import { reloadHoldAwareGrids } from "../grid/sources/content-source";
+import { holdSwitch, setIncludeHeld } from "./hold-state";
 import { collectionOfPath, entryCollection } from "./entry-model";
 import { entryBody } from "../create/add-new";
 import { collectionForDirectory } from "./collection-match";
 import { LOCALE_PLACEHOLDER } from "../canvas/asset-resolve";
-import { setEntryDraft } from "./entry-editor";
+import { setEntryHold } from "./entry-editor";
 import { openEntry } from "./entry-open";
 import { errorMessage } from "@jxsuite/schema/parse";
 import type { EntryCollection } from "./entry-model";
@@ -188,6 +188,11 @@ function activeEntryTab(): Tab | null {
   return tab && collectionOfPath(tab.documentPath) ? tab : null;
 }
 
+/** The collection of the entry in front of the author, or null. */
+function activeEntryCollection(): EntryCollection | null {
+  return collectionOfPath(activeEntryTab()?.documentPath ?? null);
+}
+
 /** The content-entry command records. */
 export function contentCommands(): AnyCommand[] {
   return [
@@ -212,41 +217,41 @@ export function contentCommands(): AnyCommand[] {
     },
     {
       args: argsSchema({
-        draft: booleanProperty(
-          "True marks the open entry a draft; false marks it published. Written as a `draft` " +
-            "field on the entry.",
+        hold: booleanProperty(
+          "True holds the open entry back from production; false releases it. Written to the " +
+            "one-field `hold` rule its collection declares.",
         ),
       }),
       category: "Document",
-      id: "content.setDraft",
+      id: "content.setHold",
       level: "document",
       menus: ["context/tab", "palette"],
       group: "3_document",
-      requires: "a content entry open",
+      requires: "a content entry whose collection has a one-field hold rule",
       when: (ctx) => ctx.document.open,
-      enablement: () => activeEntryTab() !== null,
+      enablement: () => holdSwitch(activeEntryCollection()?.def) !== null,
       undo: "document",
-      /* No `aiTool`, by studio-ui-guidelines.md §12.4's fourth deletion rule: the draft flag is ONE
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's fourth deletion rule: the hold switch is ONE
          FIELD on the entry, and the model already writes fields — `set_property` at the root path
          for a JSON entry (`mutateDocumentField` is the same `set-key` at `[]`), `write_file` for a
          frontmatter one. The state is reachable — `open_document` opens a collection file as
          readily as `content.openEntry` does — so the reason is redundancy, not reach. Six lines to
-         re-enter should a task want the flag by name rather than by key. */
+         re-enter should a task want the state by name rather than by key. */
       run: (_ctx, args) => {
         const tab = activeEntryTab();
         if (!tab) {
-          throw new Error("content.setDraft: the active document is not a content entry");
+          throw new Error("content.setHold: the active document is not a content entry");
         }
-        setEntryDraft(tab, booleanArg("content.setDraft", args, "draft"));
+        setEntryHold(tab, booleanArg("content.setHold", args, "hold"));
       },
-      title: "Set Draft",
+      title: "Set Hold",
     },
     {
       args: argsSchema({
-        include: booleanProperty("True lists entries marked `draft: true` alongside the rest."),
+        include: booleanProperty("True lists entries a `hold` rule matches alongside the rest."),
       }),
       category: "View",
-      id: "content.setIncludeDrafts",
+      id: "content.setIncludeHeld",
       level: "project",
       menus: ["palette"],
       group: "2_view",
@@ -258,16 +263,16 @@ export function contentCommands(): AnyCommand[] {
        * Set the flag, then repaint what reads it.
        *
        * The second half is the wiring, and without it this command sets a value nobody looks at
-       * again: a collection grid holds the rows it loaded once, so an author who asks to see their
-       * drafts watches an unchanged table. `draft-state.ts` cannot do it — it is imported BY the
+       * again: a collection grid holds the rows it loaded once, so an author who asks to see held
+       * entries watches an unchanged table. `hold-state.ts` cannot do it — it is imported BY the
        * listings and reaching back into the workspace from there is the cycle. The command can,
        * because a command is exactly the place where "the state changed" becomes "the app changed".
        */
       run: async (_ctx, args) => {
-        setIncludeDrafts(booleanArg("content.setIncludeDrafts", args, "include"));
-        await reloadDraftAwareGrids();
+        setIncludeHeld(booleanArg("content.setIncludeHeld", args, "include"));
+        await reloadHoldAwareGrids();
       },
-      title: "Include Drafts",
+      title: "Include Held Entries",
     },
   ];
 }

package/src/content/entry-editor.ts

@@ -16,7 +16,7 @@
  *
  * **This module is the FLOW; `surfaces/entry-editor.json` is the markup.** Everything below decides
  * something — which pane holds which tab, which collection a path belongs to, which record the
- * fields live in, which required keys are absent, what a draft flag commits into — and hands the
+ * fields live in, which required keys are absent, what a hold switch commits into — and hands the
  * surface a projection with no decisions left in it. The form itself is an island the surface
  * renders empty: `ui/schema-form.ts` hands back a host ELEMENT, and {@link renderEntryMode} places
  * it in the node the document announces.
@@ -51,7 +51,7 @@ import { paneRegion } from "../ui/regions";
 import { activateTab, workspace } from "../workspace/workspace";
 import { commitEntryFields, entryFields, mutateEntryField } from "./entry-fields";
 import type { EntryFields } from "./entry-fields";
-import { DRAFT_FIELD, DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
+import { hasHold, holdMeaning, holdOf, holdStatus, holdSwitch } from "./hold-state";
 import { collectionOfPath, missingRequired, recordCollectionOfPath } from "./entry-model";
 import { ENTRY_MODE, isRecordTab, recordPlace, showRecord } from "./record-entry";
 import { requestGridReveal } from "../grid/grid-reveal";
@@ -115,56 +115,55 @@ export function detachEntryPane(paneId: string): void {
   _active.delete(paneId);
 }
 
-// ─── Drafts ──────────────────────────────────────────────────────────────────
+// ─── Holds ───────────────────────────────────────────────────────────────────
 
 /**
- * Set this entry's draft flag. A setter, never a toggle — the pill, the command and the assistant
- * all reach the same state whatever it was before.
+ * Flip the switch this entry's collection offers (`holdSwitch`). A setter, never a toggle: the
+ * pill, the command and the assistant all reach the same state whatever it was before. Does nothing
+ * on a collection whose rules offer no switch.
  *
- * `draft: false` is written rather than removed. The absence of the key and the value `false` mean
- * the same thing to a reader, but only one of them survives a glance at the file, and an author who
- * has explicitly published something should be able to see that they did.
+ * `false` is written rather than removed. The absence of the key and the value `false` mean the
+ * same thing to a reader, but only one of them survives a glance at the file, and an author who has
+ * explicitly released something should be able to see that they did.
  */
-export function setEntryDraft(tab: Tab, draft: boolean): void {
-  transactDoc(tab, (t) => mutateEntryField(t, DRAFT_FIELD, draft));
+export function setEntryHold(tab: Tab, on: boolean): void {
+  const toggle = holdSwitch(entryCollectionOf(tab)?.def);
+  if (toggle) {
+    transactDoc(tab, (t) => mutateEntryField(t, toggle.field, on));
+  }
 }
 
-/** What the tab chip's draft pill says. A value, drawn by `surfaces/tab-strip.json`. */
-export interface DraftPill {
-  /** The word on the pill: "Draft" or "Published". */
+/** What the tab chip's pill says. A value, drawn by `surfaces/tab-strip.json`. */
+export interface HoldPill {
+  /** The word on the pill: the rule's label, or "Published". */
   text: string;
-  /** Its tooltip: what being a draft actually excludes, or that it is not one. */
+  /** Its tooltip: what being held actually does, or that it is not. */
   title: string;
-  draft: boolean;
+  held: boolean;
 }
 
 /**
- * The draft pill for a tab, or `null` when its document has no draft axis at all.
+ * The pill for a tab, or `null` when its collection states no rules.
  *
  * Drawn on the pane's tab chip (`panels/tab-strip.ts`) rather than only inside the editor, because
- * the failure this exists to prevent is publishing something you thought was private — and that
- * mistake is made while looking at a tab, not while looking at a form. It states its two words for
- * any entry whose collection declares the field, so "Published" is as visible as "Draft"; a
- * collection with no draft workflow states neither, which is what `null` means.
+ * the failure this exists to prevent is publishing something you thought was private, and that
+ * mistake is made while looking at a tab, not while looking at a form. It states its state for any
+ * entry whose collection has rules, so "Published" is as visible as "Draft"; a collection with none
+ * states neither, which is what `null` means.
  *
  * **It was the ONE piece of markup left in this file, and it was not this surface's.** It was a
- * fragment of the tab CHIP — a `<span>` lit interpolated into a `repeat()` that rebuilt on every
- * strip repaint — and it said so, and that it would convert when `panels/tab-strip.ts` converted.
- * The strip is a Jx document now, so this is a projection: two strings and a flag, drawn by the
- * chip's `status` slot, and `.entry-pill`'s rules in `styles/overlays.css` are dead with it.
+ * fragment of the tab CHIP, a `<span>` lit interpolated into a `repeat()` that rebuilt on every
+ * strip repaint. The strip is a Jx document now, so this is a projection: two strings and a flag,
+ * drawn by the chip's `status` slot.
  */
-export function entryDraftPill(tab: Tab): DraftPill | null {
-  const collection = entryCollectionOf(tab);
-  const fields = entryFields(tab);
-  if (!collection || !hasDraftAxis(collection.schema, fields)) {
+export function entryHoldPill(tab: Tab): HoldPill | null {
+  const def = entryCollectionOf(tab)?.def;
+  if (!hasHold(def)) {
     return null;
   }
-  const draft = isDraftEntry(fields);
-  return {
-    draft,
-    text: draft ? "Draft" : "Published",
-    title: draft ? DRAFT_MEANING : "Not marked a draft.",
-  };
+  const fields = entryFields(tab);
+  const label = holdOf(def, fields);
+  return { held: label !== null, text: holdStatus(def, fields), title: holdMeaning(label) };
 }
 
 // ─── The form ────────────────────────────────────────────────────────────────
@@ -255,11 +254,12 @@ function entryView(paneId: string, tab: Tab, collection: EntryCollection | null)
   if (!collection) {
     return {
       collection: "",
-      draft: false,
-      draftAxis: "hidden",
-      draftHint: DRAFT_MEANING,
       emptyLine: emptyLine(tab),
       fieldsRegion,
+      holdHint: holdMeaning(null),
+      holdLabel: "",
+      holdOn: false,
+      holdSwitch: "hidden",
       name: "",
       nextDisabled: true,
       note: "",
@@ -272,23 +272,25 @@ function entryView(paneId: string, tab: Tab, collection: EntryCollection | null)
     };
   }
   const fields = entryFields(tab);
-  const draft = isDraftEntry(fields);
+  const label = holdOf(collection.def, fields);
+  const toggle = holdSwitch(collection.def);
   const record = isRecordTab(tab);
   const place = recordPlace(tab);
   return {
     collection: collection.name,
-    draft,
-    draftAxis: hasDraftAxis(collection.schema, fields) ? "shown" : "hidden",
-    draftHint: DRAFT_MEANING,
     emptyLine: "",
     fieldsRegion,
+    holdHint: holdMeaning(label),
+    holdLabel: toggle?.label ?? "",
+    holdOn: toggle !== null && fields[toggle.field] === true,
+    holdSwitch: toggle ? "shown" : "hidden",
     // A record is called what the Content home calls it: its title field, else its row.
     name: record
       ? recordName(collection, fields, place.index)
       : (tab.documentPath?.split("/").pop() ?? "Untitled"),
     nextDisabled: place.next === null,
-    note: DRAFT_MEANING,
-    noteState: draft ? "shown" : "hidden",
+    note: holdMeaning(label),
+    noteState: label === null ? "hidden" : "shown",
     place: place.index === -1 ? "" : `${place.index + 1} of ${place.total}`,
     previousDisabled: place.previous === null,
     recordNav: record ? "shown" : "hidden",
@@ -401,7 +403,7 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
         }
         tab.session.ui.canvasMode = "grid";
       },
-      setDraft: (draft) => setEntryDraft(tab, draft),
+      setHold: (on) => setEntryHold(tab, on),
       showNext: () => {
         const { next } = recordPlace(tab);
         if (next !== null) {

package/src/content/entry-inspector.ts

@@ -3,9 +3,9 @@
  * The Inspector's Entry tab: what the Page tab draws while a collection entry is the focused
  * document (`specs/studio.md` §6, §22.5; the Content-Entry board's sidebar).
  *
- * Four things, in the board's order: the entry's **status** (its draft flag, when the collection
- * has a draft workflow, `content/draft-state.ts`), its **fields** as the collection's schema types
- * them (`ui/schema-form.ts` over `content/entry-fields.ts`, the same form and the same transacted
+ * Four things, in the board's order: the entry's **status** (what its collection's `hold` rules
+ * say, `content/hold-state.ts`), its **fields** as the collection's schema types them
+ * (`ui/schema-form.ts` over `content/entry-fields.ts`, the same form and the same transacted
  * commits as the form-only editor, so ⌘Z undoes a field here exactly as it does there), the **URL**
  * its collection page publishes it at (`content/collection-pages.ts`), and the **file** it is
  * stored in, with what that file holds.
@@ -30,13 +30,13 @@ import {
   peekCollectionPage,
 } from "./collection-pages";
 import { commitEntryFields, entryFields } from "./entry-fields";
-import { DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
+import { holdMeaning, holdOf, holdStatus, holdSwitch } from "./hold-state";
 import { entryCollection } from "./entry-model";
 import {
   absentRequiredErrors,
   fieldLabels,
   formContext,
-  setEntryDraft,
+  setEntryHold,
   titleFirst,
 } from "./entry-editor";
 import { mountEntryInspectorSurface } from "../surfaces/entry-inspector";
@@ -64,20 +64,23 @@ export function entryInspectorView(tab: Tab): EntryInspectorView {
   const name = match?.name ?? "";
   const collection = entryCollection(name);
   const fields = entryFields(tab);
-  const draftAxis = hasDraftAxis(collection?.schema, fields);
-  const draft = isDraftEntry(fields);
+  const def = collection?.def;
+  const label = holdOf(def, fields);
+  const toggle = holdSwitch(def);
   const page = name === "" ? null : peekCollectionPage(name, entryLocale(path));
   const url = page ? entryUrl(page, path, fields) : null;
   const isJson = path.endsWith(".json");
   return {
-    draft,
-    draftAxis: draftAxis ? "shown" : "hidden",
-    draftHint: DRAFT_MEANING,
     fieldsState: collection?.schema ? "form" : "none",
+    held: label !== null,
+    holdHint: holdMeaning(label),
+    holdLabel: toggle?.label ?? "",
+    holdOn: toggle !== null && fields[toggle.field] === true,
+    holdSwitch: toggle ? "shown" : "hidden",
     kind: capitalise(contentCollection(name)?.item ?? "entry"),
     path,
     region: ENTRY_INSPECTOR_REGION,
-    status: draftAxis ? (draft ? "Draft" : "Published") : "",
+    status: holdStatus(def, fields),
     storage: isJson
       ? ". Its fields are the file itself."
       : ". Fields are its frontmatter, and the body is its Markdown.",
@@ -194,7 +197,7 @@ export function renderEntryInspector(host: HTMLElement, tab: Tab): void {
         openSeo: () => {
           void runActiveReported("document.openSeo", undefined, "Entry");
         },
-        setDraft: (draft) => setEntryDraft(tab, draft),
+        setHold: (on) => setEntryHold(tab, on),
       },
       {
         fieldsSlot: (element) => {

package/src/content/entry-model.ts

@@ -18,9 +18,9 @@
  *    `grid/sources/content-source.ts`'s `collectionInfo`, and `browse/library-model.ts`'s
  *    `contentTypeFor`, since deleted); this module adds no fourth and calls the exported ones.
  *
- * **The draft axis is NOT here.** `content/draft-state.ts` owns what a draft is and whether drafts
- * are listed, because this module imports `content-source.ts` and the grid source must be able to
- * ask what a draft is — the reverse edge would be a cycle, and `import/no-cycle` is an error here.
+ * **The hold axis is NOT here.** `content/hold-state.ts` owns what a hold is and whether hrafts are
+ * listed, because this module imports `content-source.ts` and the grid source must be able to ask
+ * what a draft is — the reverse edge would be a cycle, and `import/no-cycle` is an error here.
  */
 
 import { collectionInfo } from "../grid/sources/content-source";

package/src/content/entry-summaries.ts

@@ -25,7 +25,7 @@ import {
 import { getPlatform, hasPlatform } from "../platform";
 import { isImage } from "../files/media-upload";
 import { previewFileSrc } from "../files/media-paths";
-import { hasDraftAxis, isDraftEntry } from "./draft-state";
+import { holdStatus } from "./hold-state";
 import { entryCollection } from "./entry-model";
 import { PAGES_COLLECTION, collectionKeyOfPath } from "./content-collections";
 import type { EntryFields } from "./entry-fields";
@@ -36,7 +36,7 @@ export interface EntrySummary {
   path: string;
   /** The entry's `title`, or its file name without the extension. */
   title: string;
-  /** "Draft", "Published", or "" for a collection with no draft workflow. */
+  /** A `hold` rule's label, "Published", or "" for a collection with no rules. */
   status: string;
   /** A preview URL for the entry's first image field, or "" for none. */
   thumb: string;
@@ -278,16 +278,16 @@ export function entryThumb(
 
 /** One entry's summary, from its fields. Pure. */
 export function summarize(path: string, collection: string, fields: EntryFields): EntrySummary {
-  const schema = entryCollection(collection)?.schema ?? null;
+  const definition = entryCollection(collection);
+  const schema = definition?.schema ?? null;
   const titleField = titleFieldOf(schema, fields);
   const title = titleField === null ? undefined : fields[titleField];
-  const draft = isDraftEntry(fields);
   const dateField = dateFieldOf(schema, fields);
   return {
     date: dateField === null ? "" : entryDay(fields[dateField]),
     fields: fieldTexts(schema, fields),
     path,
-    status: hasDraftAxis(schema, fields) ? (draft ? "Draft" : "Published") : "",
+    status: holdStatus(definition?.def, fields),
     thumb: entryThumb(path, fields, schema),
     title: isString(title) && title.trim() !== "" ? title : entryStem(path),
   };

package/src/content/hold-state.ts

@@ -0,0 +1,172 @@
+/**
+ * The hold axis (site-architecture.md §7.6): what a project says keeps an entry back, what state an
+ * entry is in by those rules, and whether held entries are listed. One place, every list.
+ *
+ * Jx gives no field a meaning of its own. A project names its fields and writes `hold` rules on a
+ * content type, so everything here reads those rules and nothing here knows the word "draft". The
+ * loader answers the same rules with the same code (`@jxsuite/schema/content-query`), which is what
+ * lets a badge here say what the build will actually do.
+ *
+ * It is deliberately its own module rather than a field on a pane's state and rather than a section
+ * of `entry-model.ts`. Two reasons, and the second is why the definitions live here beside the
+ * flag:
+ *
+ * 1. **The perspective is a fact about the AUTHOR, not the surface.** A filter that belonged to the
+ *    Library would answer for the Library only, and the same author would then be shown a held
+ *    entry in the collection grid, in the pages grid and in Quick Open a second later.
+ * 2. **Every list that must obey it has to be able to import it.** `entry-model.ts` asks
+ *    `grid/sources/content-source.ts` where a collection's entries live, so the grid source cannot
+ *    ask `entry-model.ts` back what a hold is: `import/no-cycle` is an error in this repo, and the
+ *    cycle would be real.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { compileHold } from "@jxsuite/schema/content-query";
+import type { HoldPredicate } from "@jxsuite/schema/content-query";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+import { reactive } from "../reactivity";
+import type { ContentSectionEntry } from "../types";
+import type { EntryFields } from "./entry-fields";
+
+/** What this module reads off a content type's definition. */
+export type HoldBearer = Pick<ContentSectionEntry, "hold">;
+
+/** The word for an entry no rule holds, on a collection that has rules. */
+export const NOT_HELD = "Published";
+
+/** The rules a definition states, or none: a value that is not a list has no rules to read. */
+function rulesOf(def: HoldBearer | null | undefined): JsonValue[] {
+  /* SAFETY: `hold` is read straight out of `project.json`, so whatever it holds is JSON. */
+  return Array.isArray(def?.hold) ? (def.hold as JsonValue[]) : [];
+}
+
+/** Each rules list's compiled answer, kept for as long as the list itself is. */
+const compiled = new WeakMap<object, HoldPredicate>();
+
+/** The compiled rules, answering nothing if they cannot compile: the build is who reports those. */
+function predicateOf(def: HoldBearer | null | undefined): HoldPredicate {
+  const rules = rulesOf(def);
+  const known = compiled.get(rules);
+  if (known) {
+    return known;
+  }
+  let predicate: HoldPredicate;
+  try {
+    predicate = compileHold(rules);
+  } catch {
+    predicate = () => {};
+  }
+  compiled.set(rules, predicate);
+  return predicate;
+}
+
+/** Whether this collection has rules at all. With none, it has no state to show. */
+export function hasHold(def: HoldBearer | null | undefined): boolean {
+  return rulesOf(def).length > 0;
+}
+
+/**
+ * The label of the rule holding this entry, or null. Takes the entry's FIELDS, whichever record
+ * they live in: `content/entry-fields.ts` answers that, because a JSON collection's entry has no
+ * frontmatter and its fields are the document.
+ */
+export function holdOf(
+  def: HoldBearer | null | undefined,
+  fields: EntryFields | null | undefined,
+): string | null {
+  if (!hasHold(def)) {
+    return null;
+  }
+  /* SAFETY: an entry's fields are its parsed frontmatter or its JSON, which is what a query reads
+     from the loader too. */
+  return predicateOf(def)((fields ?? {}) as Parameters<HoldPredicate>[0]) ?? null;
+}
+
+/** What an entry's status reads: its rule's label, {@link NOT_HELD}, or "" with no rules. */
+export function holdStatus(
+  def: HoldBearer | null | undefined,
+  fields: EntryFields | null | undefined,
+): string {
+  return hasHold(def) ? (holdOf(def, fields) ?? NOT_HELD) : "";
+}
+
+/** A rule an author can flip: one field, equal to `true`. */
+export interface HoldSwitch {
+  field: string;
+  label: string;
+}
+
+/**
+ * The switch a collection's rules offer, or null. A rule on one boolean field is a thing an author
+ * can flip. A rule on a date or a list of values has no single other state to flip to, so it is
+ * shown as a status and set by editing its field.
+ */
+export function holdSwitch(def: HoldBearer | null | undefined): HoldSwitch | null {
+  for (const rule of rulesOf(def)) {
+    if (isJsonObject(rule) && isString(rule.label) && isJsonObject(rule.when)) {
+      const fields = Object.entries(rule.when);
+      const [first] = fields;
+      if (fields.length === 1 && first?.[1] === true) {
+        return { field: first[0], label: rule.label };
+      }
+    }
+  }
+  return null;
+}
+
+/** The fields a collection's rules read, which is what a surface must repaint on. */
+export function holdFields(def: HoldBearer | null | undefined): string[] {
+  return rulesOf(def).flatMap((rule) =>
+    isJsonObject(rule) && isJsonObject(rule.when) ? Object.keys(rule.when) : [],
+  );
+}
+
+/** What being held means, in one sentence, for every surface that shows the state. */
+export function holdMeaning(label: string | null): string {
+  return label === null
+    ? "No hold rule matches this entry, so a production build publishes it."
+    : `Held: ${label}. A production build leaves it out; jx dev, Preview and preview builds keep it.`;
+}
+
+// ─── The perspective ─────────────────────────────────────────────────────────
+
+/** The perspective. `includeHeld` false, the default, hides entries a rule holds. */
+export const holdView = reactive({ includeHeld: false });
+
+/** Whether held entries are currently listed. */
+export function includingHeld(): boolean {
+  return holdView.includeHeld;
+}
+
+/**
+ * Set the perspective.
+ *
+ * A setter, never a toggle: `content.setIncludeHeld` names the STATE it reaches, so a manifest
+ * step, an assistant call and a checkbox all land on the same value however many times they run
+ * (§13.5's idempotence rule, which `tests/app-commands.test.ts` enforces).
+ *
+ * Setting the flag is all this does. Repainting the lists that read it belongs to the command, in
+ * `content/entry-commands.ts`, because a data module may not reach into the workspace.
+ */
+export function setIncludeHeld(include: boolean): void {
+  holdView.includeHeld = include;
+}
+
+/**
+ * Apply the perspective to a list.
+ *
+ * `includeHeld` true, or a collection with no rules, returns the input array unchanged (identity,
+ * not a copy), so a caller can cheaply tell that nothing was filtered.
+ */
+export function applyHoldFilter<T>(
+  items: readonly T[],
+  def: HoldBearer | null | undefined,
+  fieldsOf: (item: T) => EntryFields | null | undefined,
+  includeHeld: boolean,
+): readonly T[] {
+  return includeHeld || !hasHold(def)
+    ? items
+    : items.filter((item) => holdOf(def, fieldsOf(item)) === null);
+}