@aglyn/aglyn 1.0.0-beta.277 → 1.0.0-beta.283

package/src/lib/app-utils/stock-photos/stock-photo-picker.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type StockPhotoOrientation } from '../../plugin-manager/stock-photo-provider';
+/**
+ * STOCK PHOTOS IN THE MEDIA PICKER (AGL-4066): the wire between the
+ * console's media picker and its server route, `/api/media/stock-photos`.
+ *
+ * A person editing a site by hand searches the deployment's stock photo
+ * library from the picker's Stock photos tab and places one. The route asks
+ * core's `core.stock-photos` provider and copies the chosen photo into the
+ * library the picker is filing into through `core.media-ingest`, as the
+ * signed-in member; the placed image is always that copy, never an address
+ * at the library. This module is the shapes both sides agree on, the checks
+ * the server makes on what a browser sends, and the browser's client. It
+ * names no library: the provider's own label comes back in every answer.
+ *
+ * Every request names one library, the target: a site's (`hostId`) or the
+ * workspace's shared one (`orgId`). A hit is named back to the server by
+ * {@link StockPhotoHitRef} — the search that found it and its id — never by
+ * the addresses or the credit, so the server finds the photo again in the
+ * provider's own cached answer and nothing a browser claims about a photo
+ * is stored.
+ */
+/** The console route the picker's Stock photos tab talks to. */
+export declare const STOCK_PHOTO_PICKER_ROUTE = "/api/media/stock-photos";
+/** The library a request searches for and copies into. */
+export type StockPhotoPickerTarget = {
+    hostId: string;
+    orgId?: undefined;
+} | {
+    orgId: string;
+    hostId?: undefined;
+};
+/** The orientations the tab offers, in its order. */
+export declare const STOCK_PHOTO_PICKER_ORIENTATIONS: readonly StockPhotoOrientation[];
+/** How a search result names its photo back to the server. */
+export interface StockPhotoHitRef {
+    /** The search words exactly as searched, after {@link normalizeStockPhotoQuery}. */
+    query: string;
+    orientation: StockPhotoOrientation;
+    /** The library's own id for the photo. */
+    id: string;
+}
+/** One photo a search found, as the tab shows it. */
+export interface StockPhotoPickerHit {
+    ref: StockPhotoHitRef;
+    /** `{provider}:{id}`: what the library reuses an earlier copy by. */
+    sourceKey: string;
+    /** The size of the copy that is stored when the photo is used. */
+    width: number;
+    height: number;
+    photographer: string;
+    photographerUrl?: string;
+    /** The photo's page at the library. */
+    pageUrl: string;
+    /** The library's tags, a few, lowercase. */
+    tags: string[];
+    /** The library's own description of the photo, where it writes one. */
+    alt?: string;
+    /** The sentence the stored copy's description carries: "Photo by … on …". */
+    credit: string;
+    license: string;
+    licenseUrl: string;
+    attributionRequired: boolean;
+}
+/** The library the deployment searches, by the name its terms ask for. */
+export interface StockPhotoPickerLibrary {
+    label: string;
+}
+/** What the tab is told when it opens. */
+export type StockPhotoStatusAnswer = {
+    status: 'ready';
+    library: StockPhotoPickerLibrary;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/** What a search answers. `busy`: the library could not be asked just now. */
+export type StockPhotoSearchAnswer = {
+    status: 'ok';
+    library: StockPhotoPickerLibrary;
+    query: string;
+    orientation: StockPhotoOrientation;
+    hits: StockPhotoPickerHit[];
+} | {
+    status: 'busy';
+    message: string;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/**
+ * A stored asset as the picker places it: the media document's own fields,
+ * the ones a library pick hands on.
+ */
+export interface StockPhotoPickerMedia {
+    $id: string;
+    fileName?: string;
+    contentType?: string;
+    sizeBytes?: number;
+    url?: string;
+    cdnPath?: string;
+    folderId?: string | null;
+    alt?: string;
+    description?: string;
+    width?: number;
+    height?: number;
+    variants?: number[];
+    visibleTo?: string[];
+}
+/** What using a photo answers. `reused`: the library already held a copy, which is placed. */
+export type StockPhotoImportAnswer = {
+    status: 'ok';
+    reused: boolean;
+    media: StockPhotoPickerMedia;
+} | {
+    status: 'busy';
+    message: string;
+} | {
+    status: 'gone';
+    message: string;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/** Said when the deployment has no stock photo library. */
+export declare const STOCK_PHOTOS_UNCONFIGURED_MESSAGE: string;
+/** Said when the library could not be asked, or could not send a photo, just now. */
+export declare function stockPhotosBusyMessage(label: string): string;
+/** Said when the photo is no longer among the search's results. */
+export declare const STOCK_PHOTO_GONE_MESSAGE = "That photo is no longer in the search results. Search again and choose it from the new results.";
+/**
+ * The search words as searched: control characters dropped, runs of space
+ * made one, trimmed. `null` when nothing is left or it is longer than
+ * {@link STOCK_PHOTO_QUERY_MAX_CHARS}.
+ */
+export declare function normalizeStockPhotoQuery(value: unknown): string | null;
+/** An orientation the tab offers, `any` for anything else. */
+export declare function stockPhotoOrientationOf(value: unknown): StockPhotoOrientation;
+/** The library a request names, or `null` when it names none, or both. */
+export declare function stockPhotoTargetOf(body: unknown): StockPhotoPickerTarget | null;
+/** The photo a request names, or `null` when it is not one a search could have found. */
+export declare function stockPhotoHitRefOf(value: unknown): StockPhotoHitRef | null;
+/** `value` when it is an https address, else `undefined`: nothing else is ever linked. */
+export declare function stockPhotoSafeLink(value: unknown): string | undefined;
+/** The fields of a stored media document the picker hands on, from the document. */
+export declare function stockPhotoPickerMediaOf(mediaId: string, data: Record<string, unknown>): StockPhotoPickerMedia;
+/** Posts one JSON request to the route, with whatever credentials the caller adds. */
+export type StockPhotoPickerPost = (body: Record<string, unknown>) => Promise<Response>;
+/** The browser's side of the route, for one library. */
+export interface StockPhotoPickerClient {
+    status(): Promise<StockPhotoStatusAnswer>;
+    search(query: string, orientation: StockPhotoOrientation): Promise<StockPhotoSearchAnswer>;
+    /** The hit's small copy, or `null` when none can be had. */
+    preview(ref: StockPhotoHitRef): Promise<Blob | null>;
+    /** Copies the photo into the library, or finds the copy it holds. */
+    importPhoto(ref: StockPhotoHitRef, options?: {
+        folderId?: string | null;
+    }): Promise<StockPhotoImportAnswer>;
+}
+/**
+ * The client for one library. `post` carries the member's credentials: the
+ * console hands in `authorizedFetch` bound to the route.
+ */
+export declare function createStockPhotoPickerClient(post: StockPhotoPickerPost, target: StockPhotoPickerTarget): StockPhotoPickerClient;

package/src/lib/app-utils/stock-photos/stock-photo-picker.js

@@ -0,0 +1,193 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { STOCK_PHOTO_QUERY_MAX_CHARS } from "../../plugin-manager/stock-photo-provider.js";
+/**
+ * STOCK PHOTOS IN THE MEDIA PICKER (AGL-4066): the wire between the
+ * console's media picker and its server route, `/api/media/stock-photos`.
+ *
+ * A person editing a site by hand searches the deployment's stock photo
+ * library from the picker's Stock photos tab and places one. The route asks
+ * core's `core.stock-photos` provider and copies the chosen photo into the
+ * library the picker is filing into through `core.media-ingest`, as the
+ * signed-in member; the placed image is always that copy, never an address
+ * at the library. This module is the shapes both sides agree on, the checks
+ * the server makes on what a browser sends, and the browser's client. It
+ * names no library: the provider's own label comes back in every answer.
+ *
+ * Every request names one library, the target: a site's (`hostId`) or the
+ * workspace's shared one (`orgId`). A hit is named back to the server by
+ * {@link StockPhotoHitRef} — the search that found it and its id — never by
+ * the addresses or the credit, so the server finds the photo again in the
+ * provider's own cached answer and nothing a browser claims about a photo
+ * is stored.
+ */ /** The console route the picker's Stock photos tab talks to. */ export const STOCK_PHOTO_PICKER_ROUTE = '/api/media/stock-photos';
+/** The orientations the tab offers, in its order. */ export const STOCK_PHOTO_PICKER_ORIENTATIONS = [
+    'any',
+    'horizontal',
+    'vertical'
+];
+/** Said when the deployment has no stock photo library. */ export const STOCK_PHOTOS_UNCONFIGURED_MESSAGE = 'Stock photos are not set up here, so there is no library to search. ' + 'You can still upload your own photos in the library tabs.';
+/** Said when the library could not be asked, or could not send a photo, just now. */ export function stockPhotosBusyMessage(label) {
+    return `${label || 'The stock photo library'} is busy right now. Try again in a minute.`;
+}
+/** Said when the photo is no longer among the search's results. */ export const STOCK_PHOTO_GONE_MESSAGE = 'That photo is no longer in the search results. Search again and choose it from the new results.';
+/** The longest id a library may give a photo here. */ const MAX_ID_CHARS = 64;
+/** A library id: a site's or a workspace's document id, never a path. */ const isDocumentId = (value)=>typeof value === 'string' && value.length > 0 && value.length <= 128 && !value.includes('/') && value.trim() === value;
+/**
+ * The search words as searched: control characters dropped, runs of space
+ * made one, trimmed. `null` when nothing is left or it is longer than
+ * {@link STOCK_PHOTO_QUERY_MAX_CHARS}.
+ */ export function normalizeStockPhotoQuery(value) {
+    if (typeof value !== 'string') return null;
+    // eslint-disable-next-line no-control-regex
+    const query = value.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
+    if (!query || query.length > STOCK_PHOTO_QUERY_MAX_CHARS) return null;
+    return query;
+}
+/** An orientation the tab offers, `any` for anything else. */ export function stockPhotoOrientationOf(value) {
+    return STOCK_PHOTO_PICKER_ORIENTATIONS.includes(value) ? value : 'any';
+}
+/** The library a request names, or `null` when it names none, or both. */ export function stockPhotoTargetOf(body) {
+    const record = body != null ? body : {};
+    const hostId = record['hostId'];
+    const orgId = record['orgId'];
+    const hasHost = hostId !== undefined && hostId !== null && hostId !== '';
+    const hasOrg = orgId !== undefined && orgId !== null && orgId !== '';
+    if (hasHost === hasOrg) return null;
+    if (hasHost) return isDocumentId(hostId) ? {
+        hostId
+    } : null;
+    return isDocumentId(orgId) ? {
+        orgId
+    } : null;
+}
+/** The photo a request names, or `null` when it is not one a search could have found. */ export function stockPhotoHitRefOf(value) {
+    const record = value != null ? value : {};
+    const query = normalizeStockPhotoQuery(record['query']);
+    const id = record['id'];
+    if (!query || typeof id !== 'string' || !id || id.length > MAX_ID_CHARS || !/^[\w.-]+$/.test(id)) return null;
+    return {
+        query,
+        orientation: stockPhotoOrientationOf(record['orientation']),
+        id
+    };
+}
+/** `value` when it is an https address, else `undefined`: nothing else is ever linked. */ export function stockPhotoSafeLink(value) {
+    if (typeof value !== 'string') return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password ? url.toString() : undefined;
+    } catch (unused) {
+        return undefined;
+    }
+}
+/** The fields of a stored media document the picker hands on, from the document. */ export function stockPhotoPickerMediaOf(mediaId, data) {
+    const text = (key)=>typeof data[key] === 'string' ? data[key] : undefined;
+    const count = (key)=>typeof data[key] === 'number' && Number.isFinite(data[key]) ? data[key] : undefined;
+    const list = (key, keep)=>Array.isArray(data[key]) ? data[key].filter(keep) : undefined;
+    const media = {
+        $id: mediaId
+    };
+    const fields = {
+        fileName: text('fileName'),
+        contentType: text('contentType'),
+        sizeBytes: count('sizeBytes'),
+        url: text('url'),
+        cdnPath: text('cdnPath'),
+        alt: text('alt'),
+        description: text('description'),
+        width: count('width'),
+        height: count('height'),
+        variants: list('variants', (item)=>typeof item === 'number'),
+        visibleTo: list('visibleTo', (item)=>typeof item === 'string')
+    };
+    for (const [key, value] of Object.entries(fields)){
+        if (value !== undefined) media[key] = value;
+    }
+    if (typeof data['folderId'] === 'string' || data['folderId'] === null) media.folderId = data['folderId'];
+    return media;
+}
+/** Said when a request failed before the server could answer it. */ const UNREACHABLE = 'Stock photos could not be reached. Check your connection and try again.';
+/** What a refusal says: the route's own words, else `fallback`. */ async function refusalOf(response, fallback) {
+    const body = await response.json().catch(()=>null);
+    const said = typeof (body == null ? void 0 : body.message) === 'string' ? body.message : typeof (body == null ? void 0 : body.error) === 'string' ? body.error : '';
+    return {
+        status: 'refused',
+        message: said || fallback
+    };
+}
+/** The JSON answer of a request, or a refusal that says why there is none. */ async function answerOf(request) {
+    let response;
+    try {
+        response = await request();
+    } catch (unused) {
+        return {
+            status: 'refused',
+            message: UNREACHABLE
+        };
+    }
+    if (!response.ok) return refusalOf(response, UNREACHABLE);
+    const body = await response.json().catch(()=>null);
+    return body && typeof body.status === 'string' ? body : {
+        status: 'refused',
+        message: UNREACHABLE
+    };
+}
+/**
+ * The client for one library. `post` carries the member's credentials: the
+ * console hands in `authorizedFetch` bound to the route.
+ */ export function createStockPhotoPickerClient(post, target) {
+    const library = target.hostId ? {
+        hostId: target.hostId
+    } : {
+        orgId: target.orgId
+    };
+    return {
+        status: ()=>answerOf(()=>post(_extends({
+                    action: 'status'
+                }, library))),
+        search: (query, orientation)=>answerOf(()=>post(_extends({
+                    action: 'search'
+                }, library, {
+                    query,
+                    orientation
+                }))),
+        async preview (ref) {
+            try {
+                const response = await post(_extends({
+                    action: 'preview'
+                }, library, {
+                    ref
+                }));
+                if (response.status !== 200) return null;
+                const blob = await response.blob();
+                return blob.size && blob.type.startsWith('image/') ? blob : null;
+            } catch (unused) {
+                return null;
+            }
+        },
+        importPhoto: (ref, options)=>answerOf(()=>post(_extends({
+                    action: 'import'
+                }, library, {
+                    ref
+                }, (options == null ? void 0 : options.folderId) ? {
+                    folderId: options.folderId
+                } : {})))
+    };
+}
+
+//# sourceMappingURL=stock-photo-picker.js.map

package/src/lib/app-utils/stock-photos/stock-photo-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/app-utils/stock-photos/stock-photo-picker.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  STOCK_PHOTO_QUERY_MAX_CHARS,\n  type StockPhotoOrientation,\n} from '../../plugin-manager/stock-photo-provider'\n\n/**\n * STOCK PHOTOS IN THE MEDIA PICKER (AGL-4066): the wire between the\n * console's media picker and its server route, `/api/media/stock-photos`.\n *\n * A person editing a site by hand searches the deployment's stock photo\n * library from the picker's Stock photos tab and places one. The route asks\n * core's `core.stock-photos` provider and copies the chosen photo into the\n * library the picker is filing into through `core.media-ingest`, as the\n * signed-in member; the placed image is always that copy, never an address\n * at the library. This module is the shapes both sides agree on, the checks\n * the server makes on what a browser sends, and the browser's client. It\n * names no library: the provider's own label comes back in every answer.\n *\n * Every request names one library, the target: a site's (`hostId`) or the\n * workspace's shared one (`orgId`). A hit is named back to the server by\n * {@link StockPhotoHitRef} — the search that found it and its id — never by\n * the addresses or the credit, so the server finds the photo again in the\n * provider's own cached answer and nothing a browser claims about a photo\n * is stored.\n */\n\n/** The console route the picker's Stock photos tab talks to. */\nexport const STOCK_PHOTO_PICKER_ROUTE = '/api/media/stock-photos'\n\n/** The library a request searches for and copies into. */\nexport type StockPhotoPickerTarget = { hostId: string; orgId?: undefined } | { orgId: string; hostId?: undefined }\n\n/** The orientations the tab offers, in its order. */\nexport const STOCK_PHOTO_PICKER_ORIENTATIONS: readonly StockPhotoOrientation[] = ['any', 'horizontal', 'vertical']\n\n/** How a search result names its photo back to the server. */\nexport interface StockPhotoHitRef {\n  /** The search words exactly as searched, after {@link normalizeStockPhotoQuery}. */\n  query: string\n  orientation: StockPhotoOrientation\n  /** The library's own id for the photo. */\n  id: string\n}\n\n/** One photo a search found, as the tab shows it. */\nexport interface StockPhotoPickerHit {\n  ref: StockPhotoHitRef\n  /** `{provider}:{id}`: what the library reuses an earlier copy by. */\n  sourceKey: string\n  /** The size of the copy that is stored when the photo is used. */\n  width: number\n  height: number\n  photographer: string\n  photographerUrl?: string\n  /** The photo's page at the library. */\n  pageUrl: string\n  /** The library's tags, a few, lowercase. */\n  tags: string[]\n  /** The library's own description of the photo, where it writes one. */\n  alt?: string\n  /** The sentence the stored copy's description carries: \"Photo by … on …\". */\n  credit: string\n  license: string\n  licenseUrl: string\n  attributionRequired: boolean\n}\n\n/** The library the deployment searches, by the name its terms ask for. */\nexport interface StockPhotoPickerLibrary {\n  label: string\n}\n\n/** What the tab is told when it opens. */\nexport type StockPhotoStatusAnswer =\n  | { status: 'ready'; library: StockPhotoPickerLibrary }\n  | { status: 'unconfigured'; message: string }\n  | { status: 'refused'; message: string }\n\n/** What a search answers. `busy`: the library could not be asked just now. */\nexport type StockPhotoSearchAnswer =\n  | { status: 'ok'; library: StockPhotoPickerLibrary; query: string; orientation: StockPhotoOrientation; hits: StockPhotoPickerHit[] }\n  | { status: 'busy'; message: string }\n  | { status: 'unconfigured'; message: string }\n  | { status: 'refused'; message: string }\n\n/**\n * A stored asset as the picker places it: the media document's own fields,\n * the ones a library pick hands on.\n */\nexport interface StockPhotoPickerMedia {\n  $id: string\n  fileName?: string\n  contentType?: string\n  sizeBytes?: number\n  url?: string\n  cdnPath?: string\n  folderId?: string | null\n  alt?: string\n  description?: string\n  width?: number\n  height?: number\n  variants?: number[]\n  visibleTo?: string[]\n}\n\n/** What using a photo answers. `reused`: the library already held a copy, which is placed. */\nexport type StockPhotoImportAnswer =\n  | { status: 'ok'; reused: boolean; media: StockPhotoPickerMedia }\n  | { status: 'busy'; message: string }\n  | { status: 'gone'; message: string }\n  | { status: 'unconfigured'; message: string }\n  | { status: 'refused'; message: string }\n\n/** Said when the deployment has no stock photo library. */\nexport const STOCK_PHOTOS_UNCONFIGURED_MESSAGE =\n  'Stock photos are not set up here, so there is no library to search. ' +\n  'You can still upload your own photos in the library tabs.'\n\n/** Said when the library could not be asked, or could not send a photo, just now. */\nexport function stockPhotosBusyMessage(label: string): string {\n  return `${label || 'The stock photo library'} is busy right now. Try again in a minute.`\n}\n\n/** Said when the photo is no longer among the search's results. */\nexport const STOCK_PHOTO_GONE_MESSAGE =\n  'That photo is no longer in the search results. Search again and choose it from the new results.'\n\n/** The longest id a library may give a photo here. */\nconst MAX_ID_CHARS = 64\n\n/** A library id: a site's or a workspace's document id, never a path. */\nconst isDocumentId = (value: unknown): value is string =>\n  typeof value === 'string' && value.length > 0 && value.length <= 128 && !value.includes('/') && value.trim() === value\n\n/**\n * The search words as searched: control characters dropped, runs of space\n * made one, trimmed. `null` when nothing is left or it is longer than\n * {@link STOCK_PHOTO_QUERY_MAX_CHARS}.\n */\nexport function normalizeStockPhotoQuery(value: unknown): string | null {\n  if (typeof value !== 'string') return null\n  // eslint-disable-next-line no-control-regex\n  const query = value.replace(/[\\u0000-\\u001f\\u007f]/g, ' ').replace(/\\s+/g, ' ').trim()\n  if (!query || query.length > STOCK_PHOTO_QUERY_MAX_CHARS) return null\n  return query\n}\n\n/** An orientation the tab offers, `any` for anything else. */\nexport function stockPhotoOrientationOf(value: unknown): StockPhotoOrientation {\n  return STOCK_PHOTO_PICKER_ORIENTATIONS.includes(value as StockPhotoOrientation)\n    ? (value as StockPhotoOrientation)\n    : 'any'\n}\n\n/** The library a request names, or `null` when it names none, or both. */\nexport function stockPhotoTargetOf(body: unknown): StockPhotoPickerTarget | null {\n  const record = (body ?? {}) as Record<string, unknown>\n  const hostId = record['hostId']\n  const orgId = record['orgId']\n  const hasHost = hostId !== undefined && hostId !== null && hostId !== ''\n  const hasOrg = orgId !== undefined && orgId !== null && orgId !== ''\n  if (hasHost === hasOrg) return null\n  if (hasHost) return isDocumentId(hostId) ? { hostId } : null\n  return isDocumentId(orgId) ? { orgId } : null\n}\n\n/** The photo a request names, or `null` when it is not one a search could have found. */\nexport function stockPhotoHitRefOf(value: unknown): StockPhotoHitRef | null {\n  const record = (value ?? {}) as Record<string, unknown>\n  const query = normalizeStockPhotoQuery(record['query'])\n  const id = record['id']\n  if (!query || typeof id !== 'string' || !id || id.length > MAX_ID_CHARS || !/^[\\w.-]+$/.test(id)) return null\n  return { query, orientation: stockPhotoOrientationOf(record['orientation']), id }\n}\n\n/** `value` when it is an https address, else `undefined`: nothing else is ever linked. */\nexport function stockPhotoSafeLink(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  try {\n    const url = new URL(value)\n    return url.protocol === 'https:' && !url.username && !url.password ? url.toString() : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** The fields of a stored media document the picker hands on, from the document. */\nexport function stockPhotoPickerMediaOf(mediaId: string, data: Record<string, unknown>): StockPhotoPickerMedia {\n  const text = (key: string) => (typeof data[key] === 'string' ? (data[key] as string) : undefined)\n  const count = (key: string) => (typeof data[key] === 'number' && Number.isFinite(data[key]) ? (data[key] as number) : undefined)\n  const list = <T>(key: string, keep: (item: unknown) => item is T): T[] | undefined =>\n    Array.isArray(data[key]) ? (data[key] as unknown[]).filter(keep) : undefined\n  const media: StockPhotoPickerMedia = { $id: mediaId }\n  const fields: Partial<StockPhotoPickerMedia> = {\n    fileName: text('fileName'),\n    contentType: text('contentType'),\n    sizeBytes: count('sizeBytes'),\n    url: text('url'),\n    cdnPath: text('cdnPath'),\n    alt: text('alt'),\n    description: text('description'),\n    width: count('width'),\n    height: count('height'),\n    variants: list('variants', (item): item is number => typeof item === 'number'),\n    visibleTo: list('visibleTo', (item): item is string => typeof item === 'string'),\n  }\n  for (const [key, value] of Object.entries(fields)) {\n    if (value !== undefined) (media as unknown as Record<string, unknown>)[key] = value\n  }\n  if (typeof data['folderId'] === 'string' || data['folderId'] === null) media.folderId = data['folderId'] as string | null\n  return media\n}\n\n/** Posts one JSON request to the route, with whatever credentials the caller adds. */\nexport type StockPhotoPickerPost = (body: Record<string, unknown>) => Promise<Response>\n\n/** The browser's side of the route, for one library. */\nexport interface StockPhotoPickerClient {\n  status(): Promise<StockPhotoStatusAnswer>\n  search(query: string, orientation: StockPhotoOrientation): Promise<StockPhotoSearchAnswer>\n  /** The hit's small copy, or `null` when none can be had. */\n  preview(ref: StockPhotoHitRef): Promise<Blob | null>\n  /** Copies the photo into the library, or finds the copy it holds. */\n  importPhoto(ref: StockPhotoHitRef, options?: { folderId?: string | null }): Promise<StockPhotoImportAnswer>\n}\n\n/** Said when a request failed before the server could answer it. */\nconst UNREACHABLE = 'Stock photos could not be reached. Check your connection and try again.'\n\n/** What a refusal says: the route's own words, else `fallback`. */\nasync function refusalOf(response: Response, fallback: string): Promise<{ status: 'refused'; message: string }> {\n  const body = (await response.json().catch((): null => null)) as { message?: unknown; error?: unknown } | null\n  const said = typeof body?.message === 'string' ? body.message : typeof body?.error === 'string' ? body.error : ''\n  return { status: 'refused', message: said || fallback }\n}\n\n/** The JSON answer of a request, or a refusal that says why there is none. */\nasync function answerOf<Answer>(request: () => Promise<Response>): Promise<Answer | { status: 'refused'; message: string }> {\n  let response: Response\n  try {\n    response = await request()\n  } catch {\n    return { status: 'refused', message: UNREACHABLE }\n  }\n  if (!response.ok) return refusalOf(response, UNREACHABLE)\n  const body = (await response.json().catch((): null => null)) as Answer | null\n  return body && typeof (body as { status?: unknown }).status === 'string' ? body : { status: 'refused', message: UNREACHABLE }\n}\n\n/**\n * The client for one library. `post` carries the member's credentials: the\n * console hands in `authorizedFetch` bound to the route.\n */\nexport function createStockPhotoPickerClient(\n  post: StockPhotoPickerPost,\n  target: StockPhotoPickerTarget,\n): StockPhotoPickerClient {\n  const library = target.hostId ? { hostId: target.hostId } : { orgId: target.orgId }\n  return {\n    status: () => answerOf<StockPhotoStatusAnswer>(() => post({ action: 'status', ...library })),\n    search: (query, orientation) =>\n      answerOf<StockPhotoSearchAnswer>(() => post({ action: 'search', ...library, query, orientation })),\n    async preview(ref) {\n      try {\n        const response = await post({ action: 'preview', ...library, ref })\n        if (response.status !== 200) return null\n        const blob = await response.blob()\n        return blob.size && blob.type.startsWith('image/') ? blob : null\n      } catch {\n        return null\n      }\n    },\n    importPhoto: (ref, options) =>\n      answerOf<StockPhotoImportAnswer>(() =>\n        post({\n          action: 'import',\n          ...library,\n          ref,\n          ...(options?.folderId ? { folderId: options.folderId } : {}),\n        }),\n      ),\n  }\n}\n"],"names":["STOCK_PHOTO_QUERY_MAX_CHARS","STOCK_PHOTO_PICKER_ROUTE","STOCK_PHOTO_PICKER_ORIENTATIONS","STOCK_PHOTOS_UNCONFIGURED_MESSAGE","stockPhotosBusyMessage","label","STOCK_PHOTO_GONE_MESSAGE","MAX_ID_CHARS","isDocumentId","value","length","includes","trim","normalizeStockPhotoQuery","query","replace","stockPhotoOrientationOf","stockPhotoTargetOf","body","record","hostId","orgId","hasHost","undefined","hasOrg","stockPhotoHitRefOf","id","test","orientation","stockPhotoSafeLink","url","URL","protocol","username","password","toString","stockPhotoPickerMediaOf","mediaId","data","text","key","count","Number","isFinite","list","keep","Array","isArray","filter","media","$id","fields","fileName","contentType","sizeBytes","cdnPath","alt","description","width","height","variants","item","visibleTo","Object","entries","folderId","UNREACHABLE","refusalOf","response","fallback","json","catch","said","message","error","status","answerOf","request","ok","createStockPhotoPickerClient","post","target","library","action","search","preview","ref","blob","size","type","startsWith","importPhoto","options"],"mappings":"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"}

package/src/lib/plugin-manager/feature-plugins.d.ts

@@ -19,9 +19,11 @@ import type { OrgPermissions } from '../app-utils/org-permissions';
 import type { ReleaseFlagKey } from '../app-utils/release-flags';
 import type { SeoAuditReport } from '../app-utils/seo-audit';
 import type { SeoListingFieldKey } from '../app-utils/seo-listing-fields';
+import type { SiteStarterFacets, SiteStarterMode } from '../app-utils/site-starter';
 import type { AglynOrgBilling, OrgFeatureFlags } from '../foundation';
 import type { ComponentSchema, MdiIconProps, PresetSchema } from '../types/nodes';
 import type { Plugin, PluginId } from './plugin-manager';
+import type { SiteStarterSummary } from './plugin-site-starters';
 import type { HostThemeSource } from '../app-utils/site-theme';
 import type { HostTheme, HostThemeScheme } from '@aglyn/shared-data-types';
 import type { ComponentType, ReactNode } from 'react';
@@ -800,6 +802,19 @@ export declare const CONSOLE_WIDGET_SLOTS: {
      * gets the shell's plain name-and-address dialog instead.
      */
     readonly hostFirstRun: "hostFirstRun";
+    /**
+     * The starter picker inside "Start your site" (AGL-4049), drawn before the
+     * site exists. Props: {@link ConsoleHostStarterPickerZoneProps} — the
+     * workspace, how the site will be filled, the person's search and filter,
+     * `onPick` and `ready`.
+     *
+     * A pick is required: there is no Skip, and the listing the platform starts
+     * a site from by default comes first. A widget here lists and picks and
+     * creates nothing; the site is created by the dialog from the starter it was
+     * handed. Not a staff zone and not host-gated: the widget's own extension
+     * gates it, as on any other zone.
+     */
+    readonly hostStarterPicker: "hostStarterPicker";
     /**
      * The host setup Theme section, between the Theme picker and the editor
      * (AGL-2938). Props: {@link ConsoleHostThemeZoneProps} — the
@@ -1512,6 +1527,23 @@ export interface ConsoleArtifactPublishZoneProps {
     /** Closes it, however it was closed — cancelled, published, or refused. */
     onClose: () => void;
 }
+/** What the `hostStarterPicker` zone hands each widget (AGL-4049). */
+export interface ConsoleHostStarterPickerZoneProps {
+    /** The org the site will belong to; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** Path slug for building `/[orgSlug]/…` links. */
+    orgSlug: string;
+    /** How the site will be filled: its pages as they are, or by the AI site start. */
+    mode: SiteStarterMode;
+    /** The person's search words, as typed. */
+    search: string;
+    /** The facets the person narrowed to; an absent one is any. */
+    filter: Partial<SiteStarterFacets>;
+    /** Hands the dialog the starter the person picked. */
+    onPick: (pick: SiteStarterSummary) => void;
+    /** Reports whether the widget drew a picker; `false` gives the dialog its own default. */
+    ready: (shown: boolean) => void;
+}
 /** What the `hostTheme` zone hands each widget (AGL-2938). */
 export interface ConsoleHostThemeZoneProps {
     hostId: string;

package/src/lib/plugin-manager/feature-plugins.js

@@ -295,6 +295,18 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
    * gets the shell's plain name-and-address dialog instead.
    */ hostFirstRun: 'hostFirstRun',
     /**
+   * The starter picker inside "Start your site" (AGL-4049), drawn before the
+   * site exists. Props: {@link ConsoleHostStarterPickerZoneProps} — the
+   * workspace, how the site will be filled, the person's search and filter,
+   * `onPick` and `ready`.
+   *
+   * A pick is required: there is no Skip, and the listing the platform starts
+   * a site from by default comes first. A widget here lists and picks and
+   * creates nothing; the site is created by the dialog from the starter it was
+   * handed. Not a staff zone and not host-gated: the widget's own extension
+   * gates it, as on any other zone.
+   */ hostStarterPicker: 'hostStarterPicker',
+    /**
    * The host setup Theme section, between the Theme picker and the editor
    * (AGL-2938). Props: {@link ConsoleHostThemeZoneProps} — the
    * site, the theme the editor shows, where that theme came from, the