docs(spec,types,plugin-calendar,plugin-gantt): comments say the producers hand off the calendar / gantt block

The JSDoc around the object-calendar / object-gantt flat-key guidance, and the
comments this PR's files carry, still said ObjectView / ListView emit or
flatten into the flat spelling and that ObjectGanttSchema declares it. They now
say the producers hand the binding off in the block, the flat spelling is a
stored-document fallback the renderer still reads, and the flat keys live on
the package-local hand-off types. Comments only.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WGufzetP4CSWdmfU9t887J

Author: claude

packages/spec/src/ui/component.zod.ts

@@ -6195,8 +6195,11 @@ export type ObjectKanbanPropsParsed = z.infer<typeof ObjectKanbanPropsSchema>;
 
 /**
  * The flat per-field spellings `ObjectCalendar` keeps reading as a
- * backward-compat fallback (`getCalendarConfig`; read points recorded in
- * `liveness/page.json`, row `regions`) and that `ObjectView`/`ListView` emit on their runtime handoff. Read, but
+ * stored-document fallback (`getCalendarConfig`; read points recorded in
+ * `liveness/page.json`, row `regions`). `ObjectView`/`ListView` hand the
+ * binding off in the `calendar` block, not flat (objectstack#25923), and the
+ * flat keys live on `plugin-calendar`'s own hand-off type, not on
+ * `@object-ui/types`' `ObjectCalendarSchema`. Read, but
  * NOT authorable — one composition key per concept (Prime Directive #12, the
  * `body` → `children` precedent on {@link PageContainerProps}): the authored
  * spelling is the `calendar` object.
@@ -7522,21 +7525,22 @@ export type ObjectMapProps = z.input<typeof ObjectMapPropsSchema>;
 export type ObjectMapPropsParsed = z.infer<typeof ObjectMapPropsSchema>;
 
 /**
- * The flat `GanttConfig` spellings `getGanttConfig`'s branch 2 reads and that
- * `ObjectView` / `ListView` EMIT when they flatten `options.gantt` — objectui's
- * own `FLAT_GANTT_CONFIG_KEYS` (read points recorded in `liveness/page.json`,
- * row `regions`). Read, but
+ * The flat `GanttConfig` spellings `getGanttConfig`'s branch 2 reads as a
+ * stored-document fallback — objectui's own `FLAT_GANTT_CONFIG_KEYS` (read
+ * points recorded in `liveness/page.json`, row `regions`). `ObjectView` /
+ * `ListView` hand the binding off in the `gantt` block, not flat
+ * (objectstack#25923). Read, but
  * NOT authorable, for the reason the map's twin set above records: objectui#6469
  * inherited the objectui#5018 ruling for this block, so the `gantt` block is the
  * authoring shape, it is taken WHOLE when present, and every flat key beside it
  * is named as ignored in a dev warning.
  *
- * The flat branch is the HOT path for this block — a hand-authored `gantt` block
- * reaching the renderer through either view layer has already been flattened —
- * which is exactly why the prescription matters here: an author who learned the
- * flat spelling from a view config (or from `@object-ui/types`'
- * `ObjectGanttSchema`, which declares the whole flat face) writes it on an SDUI
- * node next, where nothing flattens anything.
+ * The block branch is the path both view layers take — they hand the `gantt`
+ * block on whole — and the flat branch is only the stored-document fallback.
+ * The prescription still matters: an author who met the flat spelling in an
+ * older stored document writes it on an SDUI node next. The flat keys live on
+ * `plugin-gantt`'s package-local hand-off type (`ObjectGanttFlatFields`), not
+ * on `@object-ui/types`' `ObjectGanttSchema`, which declares only the block.
  *
  * Membership is `GanttConfigSchema`'s own shape plus the legacy singular
  * `dependencyField` alias the flat branch still reads beside `dependenciesField`
@@ -7632,7 +7636,7 @@ function objectGanttMarker() {
  * `mobileReadOnly`.
  *
  * Measured and deliberately NOT declared: the flat `GanttConfig` spellings (the
- * flatten product — {@link OBJECT_GANTT_FLAT_CONFIG_GUIDANCE}); `title`, which
+ * stored-document fallback — {@link OBJECT_GANTT_FLAT_CONFIG_GUIDANCE}); `title`, which
  * this renderer never reads (the export-name chain is `gantt.exportFileName` →
  * `label` → the OBJECT's label → `objectName`); a row cap — the reload's `$top`
  * is the platform ceiling, spread in as core's `nonGridRowCeilingQuery()` (one
@@ -7643,7 +7647,7 @@ function objectGanttMarker() {
  * reads, `search` and `searchableFields` (sent as `$search` / `$searchFields`),
  * which `ListView` writes onto the node it generates from its toolbar Search
  * box (its `case 'gantt'` arm) — a host-generated key pair in the same position
- * as the flatten product, and not declared here.
+ * as the flat fallback spellings, and not declared here.
  *
  * VALUE posture: `gantt` is the one config block in this family whose value
  * contract is already the SPEC's — the renderer validates it against

ui/packages/plugin-calendar/src/ObjectCalendar.tsx

@@ -1470,8 +1470,9 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
    * `plugin-view`'s `ObjectView` — and app-shell reaches the first from two
    * faces, `ObjectView` (the object-view door) and `InterfaceListPage` (the
    * interface-page door). Every one of them hands this component the same
-   * shape: the shared `baseProps` bag plus whichever of `startDateField` /
-   * `endDateField` / `titleField` the author declared. NOTHING on the node
+   * shape: the shared `baseProps` bag plus a `calendar` block carrying whichever
+   * of `startDateField` / `endDateField` / `titleField` the author declared
+   * (flat on the node until objectstack#25923). NOTHING on the node
    * names the door, so there is nothing to infer from, and a door PROP would
    * have to be declared on the node's published schema and threaded through
    * four packages.

ui/packages/plugin-gantt/src/ObjectGantt.tsx

@@ -583,7 +583,7 @@ const warnedShadowedFlatGanttKeys = new Set<string>();
  * Silence is what the precedence rule costs if it is not diagnosed: two
  * spellings of ONE vocabulary (objectui#6051 proved they are one — both derive
  * from `GanttConfig`) in a single schema, one of them inert. The ruling picks
- * the author's block over the flatten product deliberately — maintainer on
+ * the author's block over the flat spelling deliberately — maintainer on
  * objectui#5018 (2026-08-17) for `plugin-map`, inherited here by objectui#6469 —
  * so the diagnostic names what was dropped instead of leaving the author to
  * infer it from a chart that renders the other spelling's values.

ui/packages/types/src/__tests__/calendar-flat-color-allday-8466.test.ts

@@ -29,6 +29,12 @@
  * renderer READS the flat spelling, not that an author should write it. The
  * README row below pins the new teaching.
  *
+ * ⚠️ Dated note, objectstack#25923 — superseded in part. The producers now hand
+ * the binding off in the `calendar` block, the flat spelling is only a
+ * stored-document fallback the renderer still reads, and the five flat
+ * declarations DID move: off `ObjectCalendarSchema`, onto `plugin-calendar`'s
+ * own hand-off type. This file now pins their absence.
+ *
  * ⚠️ Dated note — objectstack#25923. The declarations this file pinned DID move
  * after all: the five left both published faces of `ObjectCalendarSchema`
  * (they are `plugin-calendar`'s package-local hand-off type now, where the one
@@ -141,8 +147,9 @@ const CALENDAR_REGISTRATION = 'packages/plugin-calendar/src/index.tsx';
 const CALENDAR_README = 'packages/plugin-calendar/README.md';
 
 /**
- * The five field-name keys `getCalendarConfig` reads off the node FLAT (the
- * runtime handoff), and that the README authors inside the `calendar` block.
+ * The five field-name keys `getCalendarConfig` reads off the node FLAT (a
+ * stored-document fallback since objectstack#25923, when the producers moved to
+ * the block), and that the README authors inside the `calendar` block.
  */
 const FLAT_KEYS = ['titleField', 'startDateField', 'endDateField', 'allDayField', 'colorField'] as const;
 /** The three that were already declared — the precedent the two new ones join. */
@@ -469,10 +476,12 @@ describe('objectui#8466 — the renderer reads these keys, which is what the dec
   it('the README authors the five INSIDE the `calendar` block on `object-calendar`, never flat (objectui#8831)', () => {
     // This row used to pin the opposite — that the README taught the five flat,
     // "which is what makes them authorable". objectui#8831 ruled that spelling
-    // the runtime handoff: `ComponentPropsMap['object-calendar']` refuses it and
+    // the runtime handoff (since objectstack#25923 only a stored-document
+    // fallback): `ComponentPropsMap['object-calendar']` refuses it and
     // its diagnostic prescribes the `calendar` block. So the README teaches the
-    // block, and the declarations this file pins stay because the renderer
-    // READS the flat spelling, not because an author should write it.
+    // block. Since objectstack#25923 `ObjectCalendarSchema` no longer declares
+    // the five flat at all: the renderer still READS the flat spelling, typed on
+    // `plugin-calendar`'s own hand-off type, and no author should write it.
     //
     // Read off the authored nodes by brace matching, never by line or indent,
     // so a re-wrap or re-indent cannot move the verdict (objectui#8832).

ui/packages/types/src/__tests__/object-gantt-properties-bag-10859-b6.test.ts

@@ -33,7 +33,7 @@
  * ## What is particular to this node
  *
  *   - The flat mirror also declared the whole `GanttConfig` vocabulary flat on
- *     the node (`startDateField`, `viewMode`, …, the flatten product
+ *     the node (`startDateField`, `viewMode`, …, the flat spelling
  *     `getGanttConfig` reads when there is no `gantt` block) and the legacy
  *     `dependencyField` alias. Each is refused by name and pointed at the
  *     bag's `gantt` block, the home the row gives them.

ui/packages/types/src/objectql.ts

@@ -315,8 +315,10 @@ export type GanttConfig = SpecGanttConfig & {
   // The nine members below were declared ONLY in `plugin-gantt`'s package-private
   // `GanttConfigEx` intersection — the type `getGanttConfig` casts the `gantt`
   // block to. `ObjectGantt` honours every one of them on BOTH authoring faces
-  // (the `gantt: { … }` block AND the flattened top-level spelling declared on
-  // `ObjectGanttSchema`), and a type that lives inside the plugin can be
+  // (the `gantt: { … }` block AND the flattened top-level spelling, declared
+  // since objectstack#25923 on `plugin-gantt`'s own hand-off type
+  // `ObjectGanttFlatFields`, not on `ObjectGanttSchema`), and a type that lives
+  // inside the plugin can be
   // referenced by neither declaration — so the vocabulary is lifted here rather
   // than restated, and the two faces derive from ONE source that cannot fork.
   //

ui/packages/types/src/zod/objectql.zod.ts

@@ -1866,8 +1866,10 @@ const CALENDAR_DATE_ALIAS_STEM =
 /**
  * WHERE THE AUTHORED VALUE LANDS, which is what decides the consequence clause.
  *
- *   - `'binding'` — the value reaches `ObjectCalendar` as a FLAT member of the
- *     node. Every producer-fed surface is this: the view-level `calendar` block
+ *   - `'binding'` — the value reaches `ObjectCalendar` through a producer's
+ *     hand-off (since objectstack#25923 in the node's own `calendar` block,
+ *     before that as a FLAT member of the node). Every producer-fed surface is
+ *     this: the view-level `calendar` block
  *     and its legacy `options.calendar` twin, a named view's two nestings, and
  *     the flat node face itself.
  *   - `'container'` — the `object-calendar` element's OWN `calendar` container,