clivly 0.9.5 → 0.9.7

package/internal-BLKMnIIZ.cjs

@@ -0,0 +1,259 @@
+const require_projection = require("./projection-DEwL-D8R.cjs");
+const require_entity_config = require("./entity-config-CPM-Tp-d.cjs");
+//#region ../core/src/projection-draft.ts
+function emptyProjectionDraft(baseTable) {
+	return {
+		baseTable,
+		entityKey: "",
+		fieldBindings: {},
+		identity: { kind: "base_pk" },
+		joins: []
+	};
+}
+/**
+* The ON conditions implied by a foreign key between the two tables, so the
+* builder can pre-fill a join instead of making the user hand-pick columns.
+* Returns [] when no FK relates them — the user then picks manually.
+*/
+function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
+	const join = schema.find((t) => t.name === joinTable);
+	const conditions = [];
+	for (const column of join?.columnsMeta ?? []) if (column.references?.table === baseTable) conditions.push({
+		left: {
+			table: joinKey,
+			column: column.name
+		},
+		op: "eq",
+		right: {
+			table: require_projection.BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([require_projection.BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = require_projection.identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: require_projection.BASE_REF,
+		label: `${base.name} (${require_projection.BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+function draftToProjection(draft) {
+	if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
+	if (Object.keys(draft.fieldBindings).length === 0) return null;
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: draft.entityKey,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return require_entity_config.validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
+function draftErrors(draft, schema) {
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!require_projection.PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${require_projection.PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
+}
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
+function describeCardinality(draft, schema) {
+	const projection = probeProjection(draft);
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const fanning = new Set(require_entity_config.fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+Object.defineProperty(exports, "addDraftJoin", {
+	enumerable: true,
+	get: function() {
+		return addDraftJoin;
+	}
+});
+Object.defineProperty(exports, "describeCardinality", {
+	enumerable: true,
+	get: function() {
+		return describeCardinality;
+	}
+});
+Object.defineProperty(exports, "draftErrors", {
+	enumerable: true,
+	get: function() {
+		return draftErrors;
+	}
+});
+Object.defineProperty(exports, "draftRefOptions", {
+	enumerable: true,
+	get: function() {
+		return draftRefOptions;
+	}
+});
+Object.defineProperty(exports, "draftToProjection", {
+	enumerable: true,
+	get: function() {
+		return draftToProjection;
+	}
+});
+Object.defineProperty(exports, "emptyProjectionDraft", {
+	enumerable: true,
+	get: function() {
+		return emptyProjectionDraft;
+	}
+});
+Object.defineProperty(exports, "removeDraftJoin", {
+	enumerable: true,
+	get: function() {
+		return removeDraftJoin;
+	}
+});
+Object.defineProperty(exports, "suggestJoinConditions", {
+	enumerable: true,
+	get: function() {
+		return suggestJoinConditions;
+	}
+});

package/internal-BpVh_J77.mjs

@@ -0,0 +1,212 @@
+import { i as identityRefs, n as PROJECTION_KEY_MESSAGE, r as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-hnPSgH6G.mjs";
+import { h as fanOutJoins, m as validateProjection } from "./entity-config-C8IIkrmX.mjs";
+//#region ../core/src/projection-draft.ts
+function emptyProjectionDraft(baseTable) {
+	return {
+		baseTable,
+		entityKey: "",
+		fieldBindings: {},
+		identity: { kind: "base_pk" },
+		joins: []
+	};
+}
+/**
+* The ON conditions implied by a foreign key between the two tables, so the
+* builder can pre-fill a join instead of making the user hand-pick columns.
+* Returns [] when no FK relates them — the user then picks manually.
+*/
+function suggestJoinConditions(baseTable, joinTable, schema, joinKey) {
+	const join = schema.find((t) => t.name === joinTable);
+	const conditions = [];
+	for (const column of join?.columnsMeta ?? []) if (column.references?.table === baseTable) conditions.push({
+		left: {
+			table: joinKey,
+			column: column.name
+		},
+		op: "eq",
+		right: {
+			table: BASE_REF,
+			column: column.references.column
+		}
+	});
+	return conditions;
+}
+/**
+* Add a join on `joinTable`, keyed and pre-filled.
+*
+* The key is the table's own name where that is free, because it is what the
+* user already calls the table; a collision falls back to `_2`, `_3` and so on.
+* Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+* addresses the table by, so two joins sharing one would make every ref
+* ambiguous. `base` is reserved for the base table and can never be taken.
+*/
+function addDraftJoin(draft, joinTable, schema) {
+	const taken = /* @__PURE__ */ new Set([BASE_REF, ...draft.joins.map((j) => j.key)]);
+	let key = joinTable;
+	let suffix = 2;
+	while (taken.has(key)) {
+		key = `${joinTable}_${suffix}`;
+		suffix += 1;
+	}
+	return {
+		...draft,
+		joins: [...draft.joins, {
+			key,
+			table: joinTable,
+			type: "left",
+			on: suggestJoinConditions(draft.baseTable, joinTable, schema, key)
+		}]
+	};
+}
+/**
+* Remove a join, and everything that addressed it.
+*
+* Refs to a removed join are refs to a table the projection no longer declares.
+* Left in place they fail validation as "unknown ref table", which blames the
+* field — or, worse, the identity — for the join's removal. Identity falls back
+* to the base primary key, the same default a new draft starts from.
+*/
+function removeDraftJoin(draft, joinKey) {
+	const fieldBindings = Object.fromEntries(Object.entries(draft.fieldBindings).filter(([, binding]) => binding.from.table !== joinKey));
+	const identityDependsOnJoin = identityRefs(draft.identity, "").some((ref) => ref.table === joinKey);
+	return {
+		...draft,
+		joins: draft.joins.filter((join) => join.key !== joinKey),
+		fieldBindings,
+		identity: identityDependsOnJoin ? { kind: "base_pk" } : draft.identity
+	};
+}
+/**
+* Every table a field or identity may currently read from, in ref order: the
+* base table first, then each join.
+*
+* Returns [] when the base table is not in the discovered schema — there is
+* nothing truthful to offer, and inventing columns would let someone build a
+* projection that cannot compile.
+*/
+function draftRefOptions(draft, schema) {
+	const byName = new Map(schema.map((table) => [table.name, table]));
+	const base = byName.get(draft.baseTable);
+	if (!base) return [];
+	const options = [{
+		ref: BASE_REF,
+		label: `${base.name} (${BASE_REF})`,
+		columns: base.columns
+	}];
+	for (const join of draft.joins) {
+		const table = byName.get(join.table);
+		if (table) options.push({
+			ref: join.key,
+			label: `${table.name} (${join.key})`,
+			columns: table.columns
+		});
+	}
+	return options;
+}
+/** A draft becomes a projection once it has a valid key and ≥1 binding. */
+function draftToProjection(draft) {
+	if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) return null;
+	if (Object.keys(draft.fieldBindings).length === 0) return null;
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: draft.entityKey,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+const PROBE_KEY = "draft";
+/**
+* A draft rendered as a projection so the semantic checks can run against it
+* while it is being written, not only once it is finished.
+*
+* `entityKey` is stood in for rather than taken from the draft: it is the one
+* field `validateProjection` never looks at, and a half-typed key would
+* otherwise have to be valid before any join or identity could be checked. The
+* missing or malformed key is reported separately, by `draftErrors`.
+*/
+function probeProjection(draft) {
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey: PROBE_KEY,
+		baseTable: draft.baseTable,
+		joins: draft.joins,
+		fieldBindings: draft.fieldBindings,
+		identity: draft.identity
+	};
+}
+/**
+* `validateProjection` appends its own `projection.` segment to the base path it
+* is given, because in a config the base is the entity that owns the projection
+* (`entities.accounts` → `entities.accounts.projection.identity`). A draft has
+* no owning entity, so passing "projection" as the base produced
+* `projection.projection.identity` — a path no caller could match against, and
+* the reason `draftErrors` was only ever consumed as a flat list of messages.
+*
+* Passing an empty base and dropping the leading separator leaves one
+* convention: every path here starts `projection.` exactly once, whether it came
+* from this module or from the validator.
+*/
+function semanticErrors(draft, schema) {
+	return validateProjection(probeProjection(draft), schema, "").map((error) => ({
+		...error,
+		path: error.path.startsWith(".") ? error.path.slice(1) : error.path
+	}));
+}
+/**
+* Every reason this draft cannot be saved, one per cause and each anchored to
+* the section that owns it.
+*
+* One lumped "Name the object and map a field." was all this used to return for
+* an incomplete draft, at the bare path "projection". Two consequences, both
+* bad: a builder had nowhere to attach the message, and — because it returned
+* before validating — a fanning join under a `base_pk` identity stayed silent
+* until the draft was otherwise complete, which is well after the point where
+* the user chose the join.
+*/
+function draftErrors(draft, schema) {
+	const errors = [];
+	if (draft.entityKey === "") errors.push({
+		path: "projection.entityKey",
+		message: "Key is required."
+	});
+	else if (!PROJECTION_KEY_PATTERN.test(draft.entityKey)) errors.push({
+		path: "projection.entityKey",
+		message: `Key ${PROJECTION_KEY_MESSAGE}.`
+	});
+	if (Object.keys(draft.fieldBindings).length === 0) errors.push({
+		path: "projection.fieldBindings",
+		message: "Map at least one field."
+	});
+	if (draft.baseTable === "") {
+		errors.push({
+			path: "projection.baseTable",
+			message: "Pick a base table."
+		});
+		return errors;
+	}
+	errors.push(...semanticErrors(draft, schema));
+	return errors;
+}
+/**
+* Per-join fan-out, for the builder's inline cardinality hints.
+*
+* Answered from the joins alone. Joins are chosen before the key and the fields
+* are filled in, and a fan-out warning is precisely what should steer the
+* identity choice while it is being made — requiring a complete draft put the
+* hint after the decision it exists to inform.
+*/
+function describeCardinality(draft, schema) {
+	const projection = probeProjection(draft);
+	const tablesByName = new Map(schema.map((t) => [t.name, t]));
+	const fanning = new Set(fanOutJoins(projection, tablesByName).map((j) => j.key));
+	return projection.joins.map((join) => ({
+		joinKey: join.key,
+		fansOut: fanning.has(join.key)
+	}));
+}
+//#endregion
+export { draftToProjection as a, suggestJoinConditions as c, draftRefOptions as i, describeCardinality as n, emptyProjectionDraft as o, draftErrors as r, removeDraftJoin as s, addDraftJoin as t };

package/{internal-o2M7FGlR.d.mts → internal-CvlFk3KC.d.mts}

@@ -27,10 +27,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * Returns [] when no FK relates them — the user then picks manually.
  */
 declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/**
+ * Add a join on `joinTable`, keyed and pre-filled.
+ *
+ * The key is the table's own name where that is free, because it is what the
+ * user already calls the table; a collision falls back to `_2`, `_3` and so on.
+ * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+ * addresses the table by, so two joins sharing one would make every ref
+ * ambiguous. `base` is reserved for the base table and can never be taken.
+ */
+declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
+/**
+ * Remove a join, and everything that addressed it.
+ *
+ * Refs to a removed join are refs to a table the projection no longer declares.
+ * Left in place they fail validation as "unknown ref table", which blames the
+ * field — or, worse, the identity — for the join's removal. Identity falls back
+ * to the base primary key, the same default a new draft starts from.
+ */
+declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
+/** One selectable table in the builder's column pickers. */
+interface DraftRefOption {
+  columns: string[];
+  label: string;
+  ref: string;
+}
+/**
+ * Every table a field or identity may currently read from, in ref order: the
+ * base table first, then each join.
+ *
+ * Returns [] when the base table is not in the discovered schema — there is
+ * nothing truthful to offer, and inventing columns would let someone build a
+ * projection that cannot compile.
+ */
+declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+/**
+ * Every reason this draft cannot be saved, one per cause and each anchored to
+ * the section that owns it.
+ *
+ * One lumped "Name the object and map a field." was all this used to return for
+ * an incomplete draft, at the bare path "projection". Two consequences, both
+ * bad: a builder had nowhere to attach the message, and — because it returned
+ * before validating — a fanning join under a `base_pk` identity stayed silent
+ * until the draft was otherwise complete, which is well after the point where
+ * the user chose the join.
+ */
 declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+ * Per-join fan-out, for the builder's inline cardinality hints.
+ *
+ * Answered from the joins alone. Joins are chosen before the key and the fields
+ * are filled in, and a fan-out warning is precisely what should steer the
+ * identity choice while it is being made — requiring a complete draft put the
+ * hint after the decision it exists to inform.
+ */
 declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
   fansOut: boolean;
   joinKey: string;
@@ -60,9 +112,37 @@ declare function quoteIdent(name: string): string;
  * a pushed row's `id` identical to the one the view would have produced.
  */
 declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * as often as they like, so the cap belongs beside the query rather than in
+ * whichever caller happens to be passing a limit today.
+ */
+declare const PREVIEW_MAX_ROWS = 50;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * reads `row[token]`; a preview is read by a person, in a table whose headers
+ * are the field names they just typed.
+ */
+declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region ../core/src/projection-validate.d.ts
 /**
@@ -97,4 +177,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { joinFansOut as _, validateProjection as a, compileProjectionJoins as c, describeCardinality as d, draftErrors as f, fanOutJoins as g, suggestJoinConditions as h, primaryKeyColumns as i, quoteIdent as l, emptyProjectionDraft as m, coversUniqueKey as n, compileProjectionFrom as o, draftToProjection as p, hasRichMeta as r, compileProjectionIdentity as s, columnMetaFor as t, ProjectionDraft as u };
+export { fanOutJoins as C, suggestJoinConditions as S, draftErrors as _, validateProjection as a, emptyProjectionDraft as b, compileProjectionIdentity as c, compileProjectionSelect as d, quoteIdent as f, describeCardinality as g, addDraftJoin as h, primaryKeyColumns as i, compileProjectionJoins as l, ProjectionDraft as m, coversUniqueKey as n, PREVIEW_MAX_ROWS as o, DraftRefOption as p, hasRichMeta as r, compileProjectionFrom as s, columnMetaFor as t, compileProjectionPreview as u, draftRefOptions as v, joinFansOut as w, removeDraftJoin as x, draftToProjection as y };

package/{internal-wCXSELDN.d.cts → internal-DGUOLQAq.d.cts}

@@ -27,10 +27,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * Returns [] when no FK relates them — the user then picks manually.
  */
 declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
+/**
+ * Add a join on `joinTable`, keyed and pre-filled.
+ *
+ * The key is the table's own name where that is free, because it is what the
+ * user already calls the table; a collision falls back to `_2`, `_3` and so on.
+ * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
+ * addresses the table by, so two joins sharing one would make every ref
+ * ambiguous. `base` is reserved for the base table and can never be taken.
+ */
+declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
+/**
+ * Remove a join, and everything that addressed it.
+ *
+ * Refs to a removed join are refs to a table the projection no longer declares.
+ * Left in place they fail validation as "unknown ref table", which blames the
+ * field — or, worse, the identity — for the join's removal. Identity falls back
+ * to the base primary key, the same default a new draft starts from.
+ */
+declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
+/** One selectable table in the builder's column pickers. */
+interface DraftRefOption {
+  columns: string[];
+  label: string;
+  ref: string;
+}
+/**
+ * Every table a field or identity may currently read from, in ref order: the
+ * base table first, then each join.
+ *
+ * Returns [] when the base table is not in the discovered schema — there is
+ * nothing truthful to offer, and inventing columns would let someone build a
+ * projection that cannot compile.
+ */
+declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
 /** A draft becomes a projection once it has a valid key and ≥1 binding. */
 declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
+/**
+ * Every reason this draft cannot be saved, one per cause and each anchored to
+ * the section that owns it.
+ *
+ * One lumped "Name the object and map a field." was all this used to return for
+ * an incomplete draft, at the bare path "projection". Two consequences, both
+ * bad: a builder had nowhere to attach the message, and — because it returned
+ * before validating — a fanning join under a `base_pk` identity stayed silent
+ * until the draft was otherwise complete, which is well after the point where
+ * the user chose the join.
+ */
 declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/** Per-join fan-out, for the builder's inline cardinality hints. */
+/**
+ * Per-join fan-out, for the builder's inline cardinality hints.
+ *
+ * Answered from the joins alone. Joins are chosen before the key and the fields
+ * are filled in, and a fan-out warning is precisely what should steer the
+ * identity choice while it is being made — requiring a complete draft put the
+ * hint after the decision it exists to inform.
+ */
 declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
   fansOut: boolean;
   joinKey: string;
@@ -60,9 +112,37 @@ declare function quoteIdent(name: string): string;
  * a pushed row's `id` identical to the one the view would have produced.
  */
 declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * as often as they like, so the cap belongs beside the query rather than in
+ * whichever caller happens to be passing a limit today.
+ */
+declare const PREVIEW_MAX_ROWS = 50;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * reads `row[token]`; a preview is read by a person, in a table whose headers
+ * are the field names they just typed.
+ */
+declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region ../core/src/projection-validate.d.ts
 /**
@@ -97,4 +177,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { joinFansOut as _, validateProjection as a, compileProjectionJoins as c, describeCardinality as d, draftErrors as f, fanOutJoins as g, suggestJoinConditions as h, primaryKeyColumns as i, quoteIdent as l, emptyProjectionDraft as m, coversUniqueKey as n, compileProjectionFrom as o, draftToProjection as p, hasRichMeta as r, compileProjectionIdentity as s, columnMetaFor as t, ProjectionDraft as u };
+export { fanOutJoins as C, suggestJoinConditions as S, draftErrors as _, validateProjection as a, emptyProjectionDraft as b, compileProjectionIdentity as c, compileProjectionSelect as d, quoteIdent as f, describeCardinality as g, addDraftJoin as h, primaryKeyColumns as i, compileProjectionJoins as l, ProjectionDraft as m, coversUniqueKey as n, PREVIEW_MAX_ROWS as o, DraftRefOption as p, hasRichMeta as r, compileProjectionFrom as s, columnMetaFor as t, compileProjectionPreview as u, draftRefOptions as v, joinFansOut as w, removeDraftJoin as x, draftToProjection as y };