@wildo-ai/framework-knowledge 1.1.10 → 1.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +4 -2
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +459 -76
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.research-provenance.d.ts +88 -0
- package/dist/esm/framework-knowledge.research-provenance.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.research-provenance.js +140 -0
- package/dist/esm/framework-knowledge.research-provenance.js.map +1 -0
- package/dist/esm/index.d.ts +2 -0
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +2 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +5 -2
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +11 -6
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +9 -5
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +11 -7
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +4 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +3 -3
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +3 -2
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +7 -2
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +2 -2
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +26 -7
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +23 -6
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +9 -3
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +6 -4
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +2 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js +9 -3
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +8 -2
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +8 -2
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts +95 -0
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.js +111 -0
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +4 -3
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/esm/source-anchor-grammar.d.ts +70 -0
- package/dist/esm/source-anchor-grammar.d.ts.map +1 -0
- package/dist/esm/source-anchor-grammar.js +114 -0
- package/dist/esm/source-anchor-grammar.js.map +1 -0
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +8 -8
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +350 -23
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +6 -3
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +248 -9
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +2 -2
- package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.conception/method.md +12 -7
- package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +3 -3
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +12 -1
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +5 -2
- package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +13 -4
- package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +4 -3
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +5 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +12 -0
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +4 -3
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +33 -5
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +3 -3
- package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +176 -22
- package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +20 -3
- package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +3 -2
- package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +6 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +97 -23
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +30 -3
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +2 -2
- package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.governance-document-candidate/method.md +8 -6
- package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +9 -2
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +2 -2
- package/dist/knowledge/playbooks/top_down.business-model/method.md +6 -0
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +2 -2
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +12 -2
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.definition/method.md +7 -2
- package/dist/knowledge/playbooks/top_down.definition/playbook.json +5 -4
- package/dist/knowledge/playbooks/top_down.expert-personas/method.md +10 -3
- package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +3 -3
- package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.risk-register/method.md +1 -1
- package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.service-method/method.md +198 -0
- package/dist/knowledge/playbooks/top_down.service-method/playbook.json +96 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +4 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +5 -4
- package/dist/knowledge/references/acp.execution-profile.md +9 -1
- package/dist/knowledge/references/application-maturity.config.md +1 -1
- package/dist/knowledge/references/backend.inbound-channels.attachment-adoption.md +55 -0
- package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +13 -2
- package/dist/knowledge/references/backend.inbound-handlers.agents.md +10 -3
- package/dist/knowledge/references/backend.inbound-handlers.definition.md +426 -5
- package/dist/knowledge/references/backend.inbound-handlers.pipelines.md +62 -0
- package/dist/knowledge/references/blueprint.definition-contract.md +483 -0
- package/dist/knowledge/references/brand.visual-tone.config.md +26 -8
- package/dist/knowledge/references/build-plan.task-graph.config.md +238 -8
- package/dist/knowledge/references/business-model.pricing-plan.config.md +7 -0
- package/dist/knowledge/references/business-model.snapshot.validation.md +18 -0
- package/dist/knowledge/references/capability-composition.config.md +4 -3
- package/dist/knowledge/references/cli.market.generate-command.md +2 -1
- package/dist/knowledge/references/companion.technical-doc.service.md +166 -32
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +14 -0
- package/dist/knowledge/references/engine.saas-technical-doc.config.md +1 -1
- package/dist/knowledge/references/engine.saas-website.config.md +16 -44
- package/dist/knowledge/references/example.ai-use-declaration.agent.md +37 -0
- package/dist/knowledge/references/{example.authorization.service-provider-organization-wide-access.md → example.authorization.relationship-organization-wide-access.md} +2 -2
- package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +4 -3
- package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +22 -0
- package/dist/knowledge/references/example.blueprint.definition.internal-tool.md +45 -0
- package/dist/knowledge/references/example.config.app-shell.full.md +6 -3
- package/dist/knowledge/references/example.config.app-shell.hosted-components.md +4 -1
- package/dist/knowledge/references/example.config.backend.inbound-email.md +4 -2
- package/dist/knowledge/references/example.config.backend.required-floors.md +4 -2
- package/dist/knowledge/references/example.config.design-system.full.md +40 -116
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +10 -0
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +70 -14
- package/dist/knowledge/references/example.flows-actors.declared-flow.md +115 -0
- package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +12 -0
- package/dist/knowledge/references/example.inbound.email-channel-handler.md +10 -1
- package/dist/knowledge/references/example.infra.environment-config.local.md +24 -0
- package/dist/knowledge/references/example.layout-2d.registration.md +11 -0
- package/dist/knowledge/references/example.minion.contained-tick.md +1 -1
- package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +8 -10
- package/dist/knowledge/references/example.organizations.relationship-kinds.md +26 -0
- package/dist/knowledge/references/example.professional-qualifications.declaration.md +10 -0
- package/dist/knowledge/references/example.professional-qualifications.gate.md +25 -0
- package/dist/knowledge/references/example.provider.backend-module-shape.md +10 -0
- package/dist/knowledge/references/example.provider.frontend-facet.on-demand-sdk.md +41 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +4 -5
- package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +7 -5
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +0 -1
- package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +23 -7
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +52 -22
- package/dist/knowledge/references/example.resource.ui-behavior.record-template.md +81 -0
- package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +19 -20
- package/dist/knowledge/references/example.spec.composite-view.workspace.md +10 -2
- package/dist/knowledge/references/example.views.composite-view.workspace.md +10 -3
- package/dist/knowledge/references/example.website.blocks.section.md +20 -0
- package/dist/knowledge/references/example.website.blocks.site-choices.md +78 -0
- package/dist/knowledge/references/example.website.blocks.site-configs.md +155 -0
- package/dist/knowledge/references/example.website.demo.append.md +57 -0
- package/dist/knowledge/references/example.website.demo.approval.md +47 -0
- package/dist/knowledge/references/example.website.demo.celebrate.md +39 -0
- package/dist/knowledge/references/example.website.demo.complete-items.md +103 -0
- package/dist/knowledge/references/example.website.demo.connect.md +45 -0
- package/dist/knowledge/references/example.website.demo.dashboard.md +74 -0
- package/dist/knowledge/references/example.website.demo.query-answer.md +77 -0
- package/dist/knowledge/references/example.website.demo.status-lifecycle.md +71 -0
- package/dist/knowledge/references/example.website.demo.transform.md +43 -0
- package/dist/knowledge/references/example.website.page.manifest.md +2 -6
- package/dist/knowledge/references/example.website.section.bento.md +27 -0
- package/dist/knowledge/references/example.website.section.contact-form.md +15 -0
- package/dist/knowledge/references/example.website.section.factories.md +82 -0
- package/dist/knowledge/references/example.website.section.faq.md +17 -0
- package/dist/knowledge/references/example.website.section.footer-cta.md +13 -0
- package/dist/knowledge/references/example.website.section.hero.md +16 -0
- package/dist/knowledge/references/example.website.section.latest-posts.md +15 -0
- package/dist/knowledge/references/example.website.section.marquee.md +26 -0
- package/dist/knowledge/references/example.website.section.roadmap.md +25 -0
- package/dist/knowledge/references/example.website.section.site-block.md +43 -0
- package/dist/knowledge/references/example.website.section.solution-paths.md +17 -0
- package/dist/knowledge/references/example.website.section.stats.md +23 -0
- package/dist/knowledge/references/example.website.section.steps.md +15 -0
- package/dist/knowledge/references/example.website.showcase.tour.md +49 -0
- package/dist/knowledge/references/example.website.theme.composed.md +69 -0
- package/dist/knowledge/references/experience-plan.config.md +16 -0
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +6 -0
- package/dist/knowledge/references/external-connectors.frontend-provider-sdk-activation-mode.md +27 -0
- package/dist/knowledge/references/external-connectors.models.connection-target.md +99 -0
- package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +6 -0
- package/dist/knowledge/references/external-connectors.models.hook-inbound-endpoint.md +352 -0
- package/dist/knowledge/references/external-connectors.models.hook-signature-algorithms.md +64 -0
- package/dist/knowledge/references/external-connectors.models.hook-trigger-strategy.md +97 -0
- package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +61 -2
- package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +70 -0
- package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +253 -0
- package/dist/knowledge/references/external-connectors.models.subject-erasure-effect.md +105 -0
- package/dist/knowledge/references/integration-plan.config.md +21 -1
- package/dist/knowledge/references/market.references.weighted-edges.md +14 -1
- package/dist/knowledge/references/minions.tick-contract.md +2 -2
- package/dist/knowledge/references/placement-plan.config.md +75 -13
- package/dist/knowledge/references/platform.config.environment.deployment.md +9 -1
- package/dist/knowledge/references/platform.config.infrastructure-host.md +2 -0
- package/dist/knowledge/references/platform.config.platform-key-management.md +206 -0
- package/dist/knowledge/references/platform.config.saas.md +106 -14
- package/dist/knowledge/references/platform.key-management.vault-custody.md +78 -0
- package/dist/knowledge/references/presets.3d.layout-contract.md +4 -30
- package/dist/knowledge/references/presets.3d.register-layout.md +14 -36
- package/dist/knowledge/references/presets.layouts-2d.authoring.md +157 -0
- package/dist/knowledge/references/presets.layouts-2d.register-layout.md +53 -0
- package/dist/knowledge/references/presets.layouts-2d.settings.md +53 -0
- package/dist/knowledge/references/presets.layouts-2d.vocabulary.md +41 -0
- package/dist/knowledge/references/presets.models.palette-contrast.md +183 -0
- package/dist/knowledge/references/presets.models.palette-derivation.md +93 -0
- package/dist/knowledge/references/presets.models.surface-policy.defaults.md +27 -0
- package/dist/knowledge/references/presets.models.surface-variant.md +10 -0
- package/dist/knowledge/references/presets.models.theme-contract.md +136 -0
- package/dist/knowledge/references/presets.models.theme-personality-lexicon.md +81 -0
- package/dist/knowledge/references/presets.models.theme-personality.md +159 -0
- package/dist/knowledge/references/presets.themes.compose-theme.md +46 -0
- package/dist/knowledge/references/roadmap.phase.config.md +2 -16
- package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +131 -0
- package/dist/knowledge/references/saas.backend.a2a.token-budget.md +77 -11
- package/dist/knowledge/references/saas.backend.actor-execution-continuation.md +158 -0
- package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +3 -1
- package/dist/knowledge/references/saas.backend.crypto-keys.application-keys.md +100 -0
- package/dist/knowledge/references/saas.backend.custom-operation.commit-outcome-read-back.md +208 -0
- package/dist/knowledge/references/saas.backend.custom-operation.target-authority.md +33 -0
- package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +131 -1
- package/dist/knowledge/references/saas.backend.domain-module.md +76 -1
- package/dist/knowledge/references/saas.backend.email-template.definition.md +34 -0
- package/dist/knowledge/references/saas.backend.email-template.words.md +98 -0
- package/dist/knowledge/references/saas.backend.email.send.md +7 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +9 -1
- package/dist/knowledge/references/saas.backend.flows-actors.ask-person-tool.md +79 -0
- package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-case-selector.md +71 -0
- package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-declaration.md +21 -10
- package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-schedule.md +11 -5
- package/dist/knowledge/references/saas.backend.flows-actors.chat-agent-declaration.md +51 -0
- package/dist/knowledge/references/saas.backend.flows-actors.chat-reply-handler.md +207 -0
- package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +239 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +300 -3
- package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +13 -2
- package/dist/knowledge/references/saas.backend.flows-actors.operation-approval-resolvers.md +50 -0
- package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +106 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +14 -1
- package/dist/knowledge/references/saas.backend.flows-actors.retrieval-tool.md +205 -0
- package/dist/knowledge/references/saas.backend.flows-actors.tool-dispatch-obligations.md +21 -5
- package/dist/knowledge/references/saas.backend.flows.start-flow-method.md +27 -0
- package/dist/knowledge/references/saas.backend.flows.start-flow.md +47 -0
- package/dist/knowledge/references/saas.backend.pdf-template.collection-definition.md +5 -3
- package/dist/knowledge/references/saas.backend.providers.optional-runtime-peers.md +15 -25
- package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +3 -2
- package/dist/knowledge/references/saas.backend.submission-challenge.md +4 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +242 -107
- package/dist/knowledge/references/saas.config.content-security-policy.md +1 -2
- package/dist/knowledge/references/saas.data-seeding.run-ledger.md +3 -0
- package/dist/knowledge/references/saas.external-data.admin-endpoints.md +70 -3
- package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +3 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +10 -2
- package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +10 -16
- package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +7 -3
- package/dist/knowledge/references/saas.frontend.app-shell.register-shell-layout.md +97 -0
- package/dist/knowledge/references/saas.frontend.app-shell.shell-layout-contract.md +60 -0
- package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +274 -0
- package/dist/knowledge/references/saas.frontend.app-shell.use-shell-motion.md +73 -0
- package/dist/knowledge/references/saas.frontend.brand-identity.md +6 -0
- package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +13 -0
- package/dist/knowledge/references/saas.frontend.chat-sign-in-completion.md +99 -0
- package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +18 -16
- package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +9 -3
- package/dist/knowledge/references/saas.frontend.domain-module.md +5 -0
- package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +2 -1
- package/dist/knowledge/references/saas.frontend.execution-view.definition.md +17 -3
- package/dist/knowledge/references/saas.frontend.field-tiles.md +76 -0
- package/dist/knowledge/references/saas.frontend.flows-actors-view.md +10 -2
- package/dist/knowledge/references/saas.frontend.focus-indicator.md +119 -0
- package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +10 -2
- package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +7 -4
- package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +17 -16
- package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +68 -1
- package/dist/knowledge/references/saas.frontend.providers.execute-operation.md +14 -24
- package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +149 -0
- package/dist/knowledge/references/saas.frontend.resource-header-title.md +98 -34
- package/dist/knowledge/references/saas.frontend.resource-label-params.md +3 -1
- package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +17 -11
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -51
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +9 -6
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +141 -32
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +66 -4
- package/dist/knowledge/references/saas.models.agent-suspension.md +75 -0
- package/dist/knowledge/references/saas.models.agent-work-capture-settings.md +2 -2
- package/dist/knowledge/references/saas.models.agent-work-decision-contents-read.md +69 -0
- package/dist/knowledge/references/saas.models.agent-work-decision-surface.md +11 -2
- package/dist/knowledge/references/saas.models.agent-work-decision-vocabulary.md +20 -3
- package/dist/knowledge/references/saas.models.agent-work-output-review.md +3 -3
- package/dist/knowledge/references/saas.models.agent-work-override-rate.md +6 -5
- package/dist/knowledge/references/saas.models.agent-work-review-config.md +22 -4
- package/dist/knowledge/references/saas.models.analytics.value-moments.md +22 -0
- package/dist/knowledge/references/saas.models.application-agent-policy.md +28 -0
- package/dist/knowledge/references/saas.models.application-entry-points.md +45 -0
- package/dist/knowledge/references/saas.models.audit.trail-config.md +18 -5
- package/dist/knowledge/references/{saas.models.auth.service-provider-client-authentication.md → saas.models.auth.relationship-grantor-authentication.md} +54 -48
- package/dist/knowledge/references/saas.models.authorization.administrative-continuity-codes.md +4 -4
- package/dist/knowledge/references/saas.models.chat-identity-link-host.md +38 -0
- package/dist/knowledge/references/saas.models.compliance.ai-use-classification.md +179 -0
- package/dist/knowledge/references/saas.models.compliance.ai-use-posture.md +121 -0
- package/dist/knowledge/references/saas.models.config.organization-types.md +42 -82
- package/dist/knowledge/references/saas.models.conversation-threads.md +4 -3
- package/dist/knowledge/references/saas.models.crypto-keys.floors.md +22 -0
- package/dist/knowledge/references/saas.models.crypto-keys.key-management-config.md +130 -0
- package/dist/knowledge/references/saas.models.crypto-keys.local-provider.md +27 -0
- package/dist/knowledge/references/saas.models.crypto-keys.purpose-descriptor.md +403 -0
- package/dist/knowledge/references/saas.models.crypto-keys.purposes.md +84 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +24 -1
- package/dist/knowledge/references/saas.models.engine-capabilities.md +28 -0
- package/dist/knowledge/references/saas.models.evaluation-dataset-export.md +16 -9
- package/dist/knowledge/references/saas.models.evaluation-export-authorization.md +23 -6
- package/dist/knowledge/references/saas.models.external-data-conflict-vocabulary.md +53 -0
- package/dist/knowledge/references/saas.models.external-data-pipeline.md +81 -18
- package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report-config.md +28 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report.md +317 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails.md +150 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +45 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-operation-record.md +147 -0
- package/dist/knowledge/references/saas.models.flows-actors.autonomous-agents-vocabulary.md +49 -7
- package/dist/knowledge/references/saas.models.flows-actors.chat-agents-vocabulary.md +26 -0
- package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +284 -0
- package/dist/knowledge/references/saas.models.flows-actors.decision-notice-recorded-cards.md +93 -0
- package/dist/knowledge/references/saas.models.flows-actors.human-decision-decider.md +62 -0
- package/dist/knowledge/references/saas.models.flows-actors.human-input-form.md +314 -0
- package/dist/knowledge/references/saas.models.flows-actors.operation-approval-pending.md +55 -0
- package/dist/knowledge/references/saas.models.flows-actors.operation-approval-requirement.md +62 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-deadline-vocabulary.md +6 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +1 -0
- package/dist/knowledge/references/saas.models.flows.run-state.md +49 -0
- package/dist/knowledge/references/saas.models.flows.runnable-model.md +255 -0
- package/dist/knowledge/references/saas.models.frontend-on-demand-capability-contract.md +54 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +157 -42
- package/dist/knowledge/references/saas.models.http-api-binding.rest-write-operations.md +3 -3
- package/dist/knowledge/references/saas.models.http-api-population-filter.md +51 -0
- package/dist/knowledge/references/saas.models.inbound-channels.md +4 -1
- package/dist/knowledge/references/saas.models.inbound-email-domains.md +5 -5
- package/dist/knowledge/references/saas.models.inbound-email.md +2 -2
- package/dist/knowledge/references/saas.models.m2m-webhook-events.md +73 -0
- package/dist/knowledge/references/saas.models.model-cost-summary.md +56 -20
- package/dist/knowledge/references/saas.models.notifications.targets.md +25 -2
- package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +58 -6
- package/dist/knowledge/references/saas.models.on-demand-provider-capabilities.md +28 -0
- package/dist/knowledge/references/saas.models.organization-agent-policy.md +43 -0
- package/dist/knowledge/references/saas.models.organization-assigned-rows-declaration.md +73 -0
- package/dist/knowledge/references/saas.models.organization-own-rows-declaration.md +48 -0
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +6 -6
- package/dist/knowledge/references/saas.models.organizations.application-owner-codes.md +9 -10
- package/dist/knowledge/references/saas.models.organizations.organization-relationships.md +911 -0
- package/dist/knowledge/references/saas.models.organizations.professional-qualification-kinds.md +46 -0
- package/dist/knowledge/references/saas.models.organizations.professional-qualifications.md +168 -0
- package/dist/knowledge/references/{saas.models.organizations.service-provider-capability-grants.md → saas.models.organizations.relationship-capability-grants.md} +56 -35
- package/dist/knowledge/references/saas.models.organizations.relationship-grantor-controls.md +62 -0
- package/dist/knowledge/references/saas.models.organizations.relationship-invitations.md +224 -0
- package/dist/knowledge/references/saas.models.organizations.relationship-kinds.md +277 -0
- package/dist/knowledge/references/saas.models.organizations.relationship-record-separation.md +113 -0
- package/dist/knowledge/references/saas.models.privacy.legal-holds.md +68 -5
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +67 -2
- package/dist/knowledge/references/saas.models.privacy.redaction-treatments.md +13 -14
- package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +278 -40
- package/dist/knowledge/references/saas.models.provider-capabilities.md +33 -0
- package/dist/knowledge/references/saas.models.provider-usage-pricing-authority.md +50 -1
- package/dist/knowledge/references/saas.models.providers.capability-activation-policy.md +28 -0
- package/dist/knowledge/references/saas.models.providers.capability-resolution-mode.md +8 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +37 -0
- package/dist/knowledge/references/saas.models.providers.execute-operation-request.md +25 -0
- package/dist/knowledge/references/saas.models.providers.scope-reauthorization.md +1 -1
- package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +13 -1
- package/dist/knowledge/references/saas.models.rate-limit-configuration.md +4 -4
- package/dist/knowledge/references/saas.models.representative-activity.md +65 -0
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +58 -2
- package/dist/knowledge/references/saas.models.resource-config.metered-usage-recording.md +24 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +57 -11
- package/dist/knowledge/references/saas.models.resource-config.operation-base.md +20 -3
- package/dist/knowledge/references/saas.models.resource-config.operation-bulk.md +37 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-chat-command.md +39 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +1 -1
- package/dist/knowledge/references/saas.models.resource-config.operation-required-qualifications.md +30 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-scope-admissions.md +99 -2
- package/dist/knowledge/references/saas.models.resource-config.operation-submission-challenge.md +1 -1
- package/dist/knowledge/references/saas.models.resource-config.operation-union.md +0 -1
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +1 -1
- package/dist/knowledge/references/saas.models.resource-config.record-label-fields.md +23 -0
- package/dist/knowledge/references/saas.models.resource-config.request-field-offers.md +104 -0
- package/dist/knowledge/references/saas.models.resource-config.required-features.md +20 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +9 -0
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +25 -3
- package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +25 -0
- package/dist/knowledge/references/saas.models.resource-config.system-managed-fields.md +2 -1
- package/dist/knowledge/references/saas.models.resource-config.token-generation.md +1 -1
- package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +3 -2
- package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +6 -2
- package/dist/knowledge/references/saas.models.roadmap.phase-horizon.md +31 -0
- package/dist/knowledge/references/saas.models.roles.organization-defaults.md +6 -6
- package/dist/knowledge/references/saas.models.schema-family-builder.md +17 -4
- package/dist/knowledge/references/saas.models.scope-membership.md +2 -2
- package/dist/knowledge/references/saas.models.system-of-record-capabilities.md +121 -0
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +3 -2
- package/dist/knowledge/references/saas.models.systems-of-record.md +36 -1
- package/dist/knowledge/references/saas.models.work-attribution-vocabulary.md +7 -3
- package/dist/knowledge/references/saas.models.work-unit-ref.md +17 -2
- package/dist/knowledge/references/saas.public-runtime.contract.md +34 -2
- package/dist/knowledge/references/saas.specifications.assurance-control-markers.md +3 -2
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +13 -0
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +275 -13
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +5 -4
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +9 -0
- package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +16 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +10 -1
- package/dist/knowledge/references/saas.specifications.recipient-disclosures.md +111 -2
- package/dist/knowledge/references/saas.specifications.recipient-population.md +46 -0
- package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +7 -0
- package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +24 -2
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +21 -7
- package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +19 -5
- package/dist/knowledge/references/saas.specifications.subject-data-recipients.md +136 -6
- package/dist/knowledge/references/saas.website.astro.bridge.md +51 -14
- package/dist/knowledge/references/saas.website.astro.head-renderer.md +63 -27
- package/dist/knowledge/references/saas.website.astro.i18n-helper.md +39 -10
- package/dist/knowledge/references/saas.website.astro.label-key-collector.md +12 -11
- package/dist/knowledge/references/saas.website.astro.label-loader.md +38 -9
- package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +1 -2
- package/dist/knowledge/references/saas.website.astro.runtime-helper.md +48 -17
- package/dist/knowledge/references/saas.website.astro.site-context.md +17 -8
- package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +29 -8
- package/dist/knowledge/references/saas.website.blocks.actions.md +91 -0
- package/dist/knowledge/references/saas.website.blocks.band.md +41 -0
- package/dist/knowledge/references/saas.website.blocks.bento.md +70 -0
- package/dist/knowledge/references/saas.website.blocks.card-grid.md +115 -0
- package/dist/knowledge/references/saas.website.blocks.card.md +77 -0
- package/dist/knowledge/references/saas.website.blocks.cta-band.md +94 -0
- package/dist/knowledge/references/saas.website.blocks.define-block.md +123 -0
- package/dist/knowledge/references/saas.website.blocks.definitions.md +132 -0
- package/dist/knowledge/references/saas.website.blocks.faq.md +89 -0
- package/dist/knowledge/references/saas.website.blocks.feature-row.md +109 -0
- package/dist/knowledge/references/saas.website.blocks.hero.md +140 -0
- package/dist/knowledge/references/saas.website.blocks.intro.md +68 -0
- package/dist/knowledge/references/saas.website.blocks.latest-posts.md +104 -0
- package/dist/knowledge/references/saas.website.blocks.marquee.md +76 -0
- package/dist/knowledge/references/saas.website.blocks.pricing.md +395 -0
- package/dist/knowledge/references/saas.website.blocks.product-tour.md +158 -0
- package/dist/knowledge/references/saas.website.blocks.quote-cards.md +64 -0
- package/dist/knowledge/references/saas.website.blocks.roadmap.md +108 -0
- package/dist/knowledge/references/saas.website.blocks.section-slots.md +64 -0
- package/dist/knowledge/references/saas.website.blocks.solution-paths.md +71 -0
- package/dist/knowledge/references/saas.website.blocks.stats.md +183 -0
- package/dist/knowledge/references/saas.website.blocks.steps.md +69 -0
- package/dist/knowledge/references/saas.website.blocks.stylesheet.md +68 -0
- package/dist/knowledge/references/saas.website.blocks.tables.md +153 -0
- package/dist/knowledge/references/saas.website.blocks.vocabulary.md +227 -0
- package/dist/knowledge/references/saas.website.blog.bridge.md +98 -53
- package/dist/knowledge/references/saas.website.blog.collection-config.md +76 -24
- package/dist/knowledge/references/saas.website.blog.cover-resolver.md +93 -0
- package/dist/knowledge/references/saas.website.blog.frontmatter.md +104 -7
- package/dist/knowledge/references/saas.website.blog.head-renderer.md +37 -19
- package/dist/knowledge/references/saas.website.blog.index-builder.md +63 -0
- package/dist/knowledge/references/saas.website.blog.index.md +43 -0
- package/dist/knowledge/references/saas.website.blog.post-cover.md +38 -0
- package/dist/knowledge/references/saas.website.blog.post-renderer.md +113 -85
- package/dist/knowledge/references/saas.website.blog.react-mdx-integration.md +181 -0
- package/dist/knowledge/references/saas.website.blog.react-mdx-query.md +26 -0
- package/dist/knowledge/references/saas.website.blog.vocabulary-labels.md +113 -0
- package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +2 -1
- package/dist/knowledge/references/saas.website.config.site-context-loader.md +21 -1
- package/dist/knowledge/references/saas.website.consent.banner.md +1 -1
- package/dist/knowledge/references/saas.website.consent.context.md +1 -1
- package/dist/knowledge/references/saas.website.design-tokens.bundle.md +28 -6
- package/dist/knowledge/references/saas.website.design-tokens.colors.md +7 -6
- package/dist/knowledge/references/saas.website.design-tokens.compose-function.md +35 -0
- package/dist/knowledge/references/saas.website.design-tokens.compose.md +76 -0
- package/dist/knowledge/references/saas.website.design-tokens.personality-derivation.md +22 -0
- package/dist/knowledge/references/saas.website.design-tokens.personality-lexicon.md +31 -0
- package/dist/knowledge/references/saas.website.design-tokens.personality.md +82 -0
- package/dist/knowledge/references/saas.website.design-tokens.product.md +122 -0
- package/dist/knowledge/references/saas.website.design-tokens.radius.md +12 -1
- package/dist/knowledge/references/saas.website.design-tokens.readers.md +58 -0
- package/dist/knowledge/references/saas.website.design-tokens.spacing.md +61 -0
- package/dist/knowledge/references/saas.website.design-tokens.surface-depth.md +60 -0
- package/dist/knowledge/references/saas.website.design-tokens.tones.md +75 -0
- package/dist/knowledge/references/saas.website.design-tokens.typography.md +115 -0
- package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +23 -21
- package/dist/knowledge/references/saas.website.factories.define-section.md +36 -38
- package/dist/knowledge/references/saas.website.format.publication-date.md +26 -0
- package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +1 -1
- package/dist/knowledge/references/saas.website.label-keys.format.md +2 -2
- package/dist/knowledge/references/saas.website.label-pack.validator.md +7 -8
- package/dist/knowledge/references/saas.website.labels.section-labels.md +34 -0
- package/dist/knowledge/references/saas.website.legal.public-document-links.md +19 -4
- package/dist/knowledge/references/saas.website.locale-switcher.label-keys.md +35 -0
- package/dist/knowledge/references/saas.website.menu.icons.md +123 -0
- package/dist/knowledge/references/saas.website.menu.label-keys.md +112 -0
- package/dist/knowledge/references/saas.website.menu.schema.md +92 -0
- package/dist/knowledge/references/saas.website.menu.vocabulary.md +79 -0
- package/dist/knowledge/references/saas.website.motion.demo-player.md +105 -0
- package/dist/knowledge/references/saas.website.motion.demo-scenario.md +460 -0
- package/dist/knowledge/references/saas.website.motion.demo.md +324 -0
- package/dist/knowledge/references/saas.website.motion.element-attributes.md +115 -0
- package/dist/knowledge/references/saas.website.motion.reveal-renditions.md +67 -0
- package/dist/knowledge/references/saas.website.motion.stylesheet.md +82 -0
- package/dist/knowledge/references/saas.website.motion.tempo-table.md +99 -0
- package/dist/knowledge/references/saas.website.motion.tokens.md +46 -0
- package/dist/knowledge/references/saas.website.motion.vocabulary.md +85 -0
- package/dist/knowledge/references/saas.website.page-layout.component.md +34 -8
- package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +4 -4
- package/dist/knowledge/references/saas.website.page-manifest.route-path.md +1 -1
- package/dist/knowledge/references/saas.website.page-manifest.schema.md +25 -29
- package/dist/knowledge/references/saas.website.page-manifest.seo.md +1 -1
- package/dist/knowledge/references/saas.website.page-navigation.md +44 -0
- package/dist/knowledge/references/saas.website.page.context.md +9 -2
- package/dist/knowledge/references/saas.website.primitives.button.md +6 -6
- package/dist/knowledge/references/saas.website.primitives.heading.md +17 -18
- package/dist/knowledge/references/saas.website.primitives.image.md +18 -15
- package/dist/knowledge/references/saas.website.primitives.internal-button.md +11 -12
- package/dist/knowledge/references/saas.website.primitives.internal-link.md +11 -35
- package/dist/knowledge/references/saas.website.primitives.link.md +22 -11
- package/dist/knowledge/references/saas.website.primitives.text.md +10 -8
- package/dist/knowledge/references/saas.website.product.atoms.md +366 -0
- package/dist/knowledge/references/saas.website.product.figures.md +320 -0
- package/dist/knowledge/references/saas.website.product.hooks.md +278 -0
- package/dist/knowledge/references/saas.website.product.panels.md +324 -0
- package/dist/knowledge/references/saas.website.product.stylesheet.md +1086 -0
- package/dist/knowledge/references/saas.website.refs.section.md +2 -2
- package/dist/knowledge/references/saas.website.root-config.schema.md +34 -17
- package/dist/knowledge/references/saas.website.routing.link-target.md +70 -0
- package/dist/knowledge/references/saas.website.routing.localized-path.md +15 -8
- package/dist/knowledge/references/saas.website.runtime.context.md +44 -17
- package/dist/knowledge/references/saas.website.section.component.md +21 -19
- package/dist/knowledge/references/saas.website.sections.category-enum.md +21 -2
- package/dist/knowledge/references/saas.website.sections.definition-schema.md +47 -39
- package/dist/knowledge/references/saas.website.site-footer.menu.md +47 -0
- package/dist/knowledge/references/saas.website.site-header.component.md +100 -0
- package/dist/knowledge/references/saas.website.site-header.scroll-behavior.md +26 -0
- package/dist/knowledge/references/saas.website.stacking.md +86 -0
- package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +162 -0
- package/dist/knowledge/references/saas.website.use-blog-index.hook.md +27 -0
- package/dist/knowledge/references/saas.website.use-label.hook.md +6 -4
- package/dist/knowledge/references/service-method.config.md +270 -0
- package/dist/knowledge/references/website-plan.config.md +544 -32
- package/dist/knowledge/references/website-plan.menu-placement.md +118 -0
- package/dist/knowledge/references/website-plan.page-kind-essentials.md +42 -0
- package/dist/knowledge/references/website-plan.page-routes.md +39 -0
- package/dist/knowledge/references/workers.node.worker-init-contract.md +4 -2
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +73 -9
- package/dist/knowledge/references/zod.decorators.chrome-modes.md +92 -0
- package/dist/knowledge/references/zod.decorators.data-categories.md +101 -11
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +75 -6
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +23 -1
- package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +41 -7
- package/dist/knowledge/references/zod.decorators.file-schema.md +6 -5
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +25 -9
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +15 -3
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +4 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +32 -4
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +44 -5
- package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +130 -9
- package/dist/knowledge/references/zod.factories.bigdecimal.md +17 -8
- package/dist/knowledge/references/zod.factories.code.md +18 -9
- package/dist/knowledge/references/zod.factories.duration.md +23 -14
- package/dist/knowledge/references/zod.factories.money.md +24 -15
- package/dist/knowledge/references/zod.factories.phone.md +23 -14
- package/dist/knowledge/references/zod.factories.range.md +5 -1
- package/dist/knowledge/registries/assurance-authority-bases.json +3 -3
- package/dist/knowledge/registries/framework-topics.json +2411 -139
- package/dist/knowledge/registries/playbooks.json +51 -30
- package/dist/knowledge/registries/source-tags.json +8500 -4768
- package/dist/knowledge/rules/database-migration-obligation.md +11 -5
- package/dist/knowledge/skills/INDEX.md +60 -33
- package/dist/knowledge/skills/agent-work-review/SKILL.md +86 -23
- package/dist/knowledge/skills/agent-work-review/references/framework-actor-execution-continuation-api.md +203 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-capture-settings-api.md +2 -2
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-decision-contents-api.md +79 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-output-review-api.md +4 -4
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-override-rate-api.md +6 -5
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-config-api.md +22 -4
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +15 -3
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-vocabulary-api.md +20 -3
- package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-dataset-export-api.md +16 -9
- package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-export-authorization-api.md +24 -7
- package/dist/knowledge/skills/agent-work-review/references/framework-human-input-form-api.md +341 -0
- package/dist/knowledge/skills/ai-use-declaration/SKILL.md +192 -0
- package/dist/knowledge/skills/ai-use-declaration/references/choosing-the-domain-and-class.md +73 -0
- package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-classification-api.md +194 -0
- package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-posture-api.md +136 -0
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +27 -9
- package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
- package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +6 -6
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +124 -3
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-assigned-rows-declaration-api.md +90 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-own-rows-declaration-api.md +59 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +6 -6
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +79 -2
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +35 -1
- package/dist/knowledge/skills/backend-custom-operation/references/framework-assurance-control-markers.md +3 -2
- package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +3 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +20 -3
- package/dist/knowledge/skills/backend-custom-operation/references/framework-target-authority-api.md +61 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +368 -1
- package/dist/knowledge/skills/blueprint-authoring/SKILL.md +189 -0
- package/dist/knowledge/skills/blueprint-authoring/references/blueprint-content-kinds.md +29 -0
- package/dist/knowledge/skills/blueprint-authoring/references/framework-blueprint-definition-api.md +490 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +127 -2
- package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +15 -3
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +26 -8
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-style-word-lexicon-api.md +126 -0
- package/dist/knowledge/skills/chat-agent-conversations/SKILL.md +163 -0
- package/dist/knowledge/skills/chat-agent-conversations/references/framework-chat-conversations-api.md +295 -0
- package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +8 -6
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +134 -33
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +4 -3
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +13 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +34 -7
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +10 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +37 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +178 -4
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-population.md +46 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +485 -61
- package/dist/knowledge/skills/config-app-shell/SKILL.md +57 -28
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +20 -18
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +7 -3
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +13 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-brand-identity-api.md +20 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +17 -6
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +24 -22
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +528 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +245 -162
- package/dist/knowledge/skills/config-design-system/references/design-system-file.md +5 -1
- package/dist/knowledge/skills/config-design-system/references/framework-focus-indicator-api.md +182 -0
- package/dist/knowledge/skills/config-design-system/references/framework-palette-contrast-api.md +195 -0
- package/dist/knowledge/skills/config-design-system/references/framework-palette-derivation-api.md +108 -0
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +37 -0
- package/dist/knowledge/skills/config-design-system/references/framework-theme-composition-api.md +235 -0
- package/dist/knowledge/skills/config-design-system/references/theme-design-principles.md +202 -0
- package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +16 -5
- package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +1 -1
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +7 -1
- package/dist/knowledge/skills/config-saas/SKILL.md +2 -0
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +11 -3
- package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +18 -5
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +314 -0
- package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +29 -1
- package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +8 -0
- package/dist/knowledge/skills/config-saas/references/framework-content-security-policy-api.md +1 -2
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +1182 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +61 -0
- package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +56 -11
- package/dist/knowledge/skills/config-saas/references/framework-value-moments-api.md +22 -0
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +106 -14
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +5 -3
- package/dist/knowledge/skills/config-saas-backend/references/framework-application-owner-organization-codes-api.md +9 -10
- package/dist/knowledge/skills/config-saas-backend/references/framework-federated-identity-provider-private-networks-api.md +6 -4
- package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +155 -92
- package/dist/knowledge/skills/configure-billing/SKILL.md +14 -0
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +10 -0
- package/dist/knowledge/skills/configure-billing/references/framework-metered-usage-recording-api.md +109 -0
- package/dist/knowledge/skills/configure-coding-agent/references/framework-acp-execution-profile-api.md +18 -2
- package/dist/knowledge/skills/email-add-template/SKILL.md +46 -5
- package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +7 -0
- package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +134 -0
- package/dist/knowledge/skills/engine-product-definitions/references/framework-metered-usage-recording-api.md +28 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +71 -14
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-a2a-token-budget-api.md +95 -13
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +9 -1
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +98 -9
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +44 -16
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-autonomous-agent-api.md +160 -23
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-inbound-agents-api.md +10 -3
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/tool-posture.md +14 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +281 -20
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +70 -14
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-behavior-reports-api.md +451 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +406 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-operation-record-api.md +201 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-suspension-api.md +172 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-ask-person-tool-api.md +121 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +7 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-realtime-catalog.md +63 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +324 -7
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +95 -6
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-model-spend-limits-api.md +255 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +150 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-retrieval-tool-api.md +251 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +112 -16
- package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +339 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-flow-model-api.md +264 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +133 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/references/step-kinds.md +16 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +91 -5
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +45 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +14 -3
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +13 -6
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +5 -4
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +27 -17
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +136 -14
- package/dist/knowledge/skills/human-decision-notices/SKILL.md +150 -0
- package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +292 -0
- package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +340 -0
- package/dist/knowledge/skills/i18n-label-generation/SKILL.md +17 -1
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +1 -1
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +4 -1
- package/dist/knowledge/skills/inbound-channels/SKILL.md +66 -8
- package/dist/knowledge/skills/inbound-channels/references/email-channel.md +34 -1
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +78 -6
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-email-api.md +8 -8
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +434 -6
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-pipelines-api.md +73 -0
- package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +1 -1
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +24 -13
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +107 -2
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +9 -1
- package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +2 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +294 -0
- package/dist/knowledge/skills/layout-2d-adoption/SKILL.md +158 -0
- package/dist/knowledge/skills/layout-2d-adoption/references/choosing-a-layout.md +43 -0
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-authoring-api.md +167 -0
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-registration-api.md +101 -0
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-settings-api.md +59 -0
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +415 -0
- package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +1 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +65 -32
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +14 -36
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +7 -3
- package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +4 -2
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +14 -1
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +9 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +9 -0
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +2 -1
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +2 -1
- package/dist/knowledge/skills/minion-authoring/examples/contained-tick.example.md +1 -1
- package/dist/knowledge/skills/minion-authoring/references/framework-minion-tick-contract.md +2 -2
- package/dist/knowledge/skills/model-cost-attribution/SKILL.md +40 -10
- package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +57 -2
- package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-summary-api.md +57 -21
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-attribution-api.md +7 -3
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +150 -4
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +9 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +81 -1
- package/dist/knowledge/skills/module-relationships/SKILL.md +50 -27
- package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +8 -4
- package/dist/knowledge/skills/organization-relationships/SKILL.md +668 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-organization-relationships-api.md +1233 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-capability-grants-api.md +243 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-grantor-authentication-api.md +284 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-kinds-api.md +521 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-record-separation-api.md +162 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-representative-activity-api.md +145 -0
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-collection-template-api.md +5 -3
- package/dist/knowledge/skills/professional-qualifications/SKILL.md +173 -0
- package/dist/knowledge/skills/professional-qualifications/references/choosing-who-may-decide.md +53 -0
- package/dist/knowledge/skills/professional-qualifications/references/framework-operation-approval-requirement-api.md +67 -0
- package/dist/knowledge/skills/professional-qualifications/references/framework-operation-required-qualifications-api.md +39 -0
- package/dist/knowledge/skills/professional-qualifications/references/framework-professional-qualifications-api.md +223 -0
- package/dist/knowledge/skills/provider-address-lookup/SKILL.md +1 -1
- package/dist/knowledge/skills/provider-address-lookup/references/framework-browser-operation-policy-api.md +3 -3
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +138 -4
- package/dist/knowledge/skills/provider-backend-package/references/framework-optional-runtime-peers.md +32 -28
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-augmentation-api.md +16 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +6 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-inbound-endpoint-api.md +634 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +70 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +61 -2
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-subject-erasure-effect-api.md +222 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +9 -5
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +9 -2
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +47 -5
- package/dist/knowledge/skills/provider-frontend-module/references/framework-on-demand-capabilities-api.md +306 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +11 -3
- package/dist/knowledge/skills/provider-operation-calls/SKILL.md +26 -14
- package/dist/knowledge/skills/provider-operation-calls/references/browser-door-answers.md +56 -18
- package/dist/knowledge/skills/provider-operation-calls/references/framework-browser-operation-policy-api.md +1 -1
- package/dist/knowledge/skills/provider-operation-calls/references/framework-frontend-execute-operation-api.md +143 -25
- package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-operation-executor-api.md +6 -0
- package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-scope-reauthorization-api.md +9 -6
- package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +256 -1
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +71 -35
- package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +27 -13
- package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +32 -12
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +132 -55
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +49 -4
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +58 -2
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +137 -0
- package/dist/knowledge/skills/resource-chat-commands/references/framework-resource-chat-command-contract.md +72 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +102 -4
- package/dist/knowledge/skills/resource-config-wiring/references/framework-administrative-continuity-codes-api.md +4 -4
- package/dist/knowledge/skills/resource-config-wiring/references/framework-authority-audit-interpretation.md +17 -8
- package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +6 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-approval-api.md +323 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +18 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-bulk-api.md +159 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +60 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-request-field-offers-api.md +168 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-required-features-api.md +20 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +1 -1
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +3 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +195 -23
- package/dist/knowledge/skills/resource-config-wiring/references/framework-scope-admissions-api.md +108 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +242 -107
- package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +176 -10
- package/dist/knowledge/skills/resource-config-wiring/references/framework-webhook-events-api.md +116 -0
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +88 -50
- package/dist/knowledge/skills/resource-external-data/SKILL.md +280 -64
- package/dist/knowledge/skills/resource-external-data/references/bidirectional-pipelines.md +335 -0
- package/dist/knowledge/skills/resource-external-data/references/declared-expressions.md +18 -6
- package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +71 -12
- package/dist/knowledge/skills/resource-external-data/references/facet-augmentations.md +6 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +81 -18
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +238 -49
- package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +111 -11
- package/dist/knowledge/skills/resource-external-data/references/framework-system-of-record-capabilities-api.md +145 -0
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +30 -4
- package/dist/knowledge/skills/resource-external-data/references/odata-v2-sources.md +21 -9
- package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +61 -14
- package/dist/knowledge/skills/resource-external-data/references/provenance-cue.md +18 -2
- package/dist/knowledge/skills/resource-external-data/references/rate-budgets-and-pacing.md +3 -1
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +39 -13
- package/dist/knowledge/skills/resource-external-data/references/remote-references.md +17 -7
- package/dist/knowledge/skills/resource-external-data/references/requested-keys.md +104 -0
- package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +1 -1
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +17 -4
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +2 -2
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +1 -1
- package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +6 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +31 -1
- package/dist/knowledge/skills/resource-retention-binding/SKILL.md +3 -1
- package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +68 -5
- package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +25 -0
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +26 -10
- package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +23 -7
- package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +9 -7
- package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +2 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +79 -6
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-erasure-scrub-treatments-api.md +19 -22
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +127 -12
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +17 -4
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +32 -4
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +44 -5
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +116 -66
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-system-managed-fields-api.md +2 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +203 -18
- package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +6 -0
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +155 -76
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +19 -17
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +120 -1
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +41 -7
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-field-tiles-api.md +114 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +168 -58
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +25 -9
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +15 -3
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +151 -1
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +144 -57
- package/dist/knowledge/skills/resource-ui-behavior/references/record-page-anatomy.md +131 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +57 -31
- package/dist/knowledge/skills/resource-ui-behavior/references/visual-quality-rubric.md +56 -0
- package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +16 -1
- package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +15 -8
- package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +3 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +42 -11
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +141 -32
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +66 -4
- package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +5 -4
- package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +5 -4
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +9 -0
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +15 -7
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +71 -14
- package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +19 -5
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +14 -5
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -1
- package/dist/knowledge/skills/views-add-custom-view/references/framework-focus-indicator-api.md +145 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -0
- package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +13 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +11 -4
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +11 -2
- package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +17 -3
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +61 -25
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +251 -78
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1064 -192
- package/dist/knowledge/skills/website-building-blocks/SKILL.md +337 -0
- package/dist/knowledge/skills/website-building-blocks/references/framework-website-blocks-api.md +3050 -0
- package/dist/knowledge/skills/website-building-blocks/references/framework-website-demo-examples.md +627 -0
- package/dist/knowledge/skills/website-building-blocks/references/framework-website-product-kit-api.md +3309 -0
- package/dist/knowledge/skills/website-building-blocks/references/website-visual-quality-rubric.md +75 -0
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +39 -18
- package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +8 -12
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +18 -5
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +84 -28
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +67 -64
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +58 -23
- package/dist/knowledge/skills/website-inbound-contact-forms/references/framework-submission-challenge-api.md +5 -1
- package/dist/knowledge/skills/website-label-pack/SKILL.md +24 -17
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +112 -77
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +24 -13
- package/dist/knowledge/skills/website-motion-design/SKILL.md +277 -0
- package/dist/knowledge/skills/website-motion-design/references/framework-motion-api.md +1562 -0
- package/dist/knowledge/skills/website-motion-design/references/industry-practice.md +28 -0
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +255 -397
- package/dist/knowledge/skills/website-navigation-authoring/references/framework-menu-api.md +712 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +28 -6
- package/dist/knowledge/skills/website-navigation-authoring/references/menu-keys-and-styling.md +151 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +131 -326
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +160 -67
- package/dist/knowledge/skills/website-page-authoring/references/framework-page-kinds-api.md +982 -0
- package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +24 -3
- package/dist/knowledge/skills/website-page-authoring/references/homepage-content-and-art-direction.md +19 -0
- package/dist/knowledge/skills/website-page-authoring/references/page-kinds.md +118 -0
- package/dist/knowledge/skills/website-page-variants/SKILL.md +70 -69
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +48 -28
- package/dist/knowledge/skills/website-section-comparison/SKILL.md +1171 -0
- package/dist/knowledge/skills/website-section-comparison/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-comparison/references/framework-website-tables-api.md +487 -0
- package/dist/knowledge/skills/website-section-contact/SKILL.md +408 -185
- package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-cta/SKILL.md +398 -234
- package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-faq/SKILL.md +561 -302
- package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-faq/references/framework-website-faq-api.md +489 -0
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +647 -274
- package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +572 -264
- package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +532 -233
- package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-hero/SKILL.md +603 -332
- package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +198 -120
- package/dist/knowledge/skills/website-section-how-it-works/SKILL.md +1150 -0
- package/dist/knowledge/skills/website-section-how-it-works/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-how-it-works/references/framework-website-steps-api.md +337 -0
- package/dist/knowledge/skills/website-section-integrations/SKILL.md +974 -0
- package/dist/knowledge/skills/website-section-integrations/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-integrations/references/framework-website-marquee-api.md +825 -0
- package/dist/knowledge/skills/website-section-latest-posts/SKILL.md +928 -0
- package/dist/knowledge/skills/website-section-latest-posts/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-latest-posts/references/framework-website-latest-posts-api.md +465 -0
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +549 -378
- package/dist/knowledge/skills/website-section-pricing/examples/pricing-offers.example.md +77 -0
- package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +2 -1
- package/dist/knowledge/skills/website-section-pricing/references/framework-website-pricing-api.md +670 -0
- package/dist/knowledge/skills/website-section-problem/SKILL.md +1150 -0
- package/dist/knowledge/skills/website-section-problem/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-problem/references/framework-website-card-grid-api.md +664 -0
- package/dist/knowledge/skills/website-section-product-showcase/SKILL.md +1322 -0
- package/dist/knowledge/skills/website-section-product-showcase/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-card-grid-api.md +533 -0
- package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-product-tour-api.md +917 -0
- package/dist/knowledge/skills/website-section-roadmap/SKILL.md +1133 -0
- package/dist/knowledge/skills/website-section-roadmap/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-roadmap/references/framework-website-roadmap-api.md +475 -0
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +739 -315
- package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +197 -119
- package/dist/knowledge/skills/website-section-social-proof/references/framework-website-quote-cards-api.md +623 -0
- package/dist/knowledge/skills/website-section-solution-paths/SKILL.md +1057 -0
- package/dist/knowledge/skills/website-section-solution-paths/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-solution-paths/references/framework-website-solution-paths-api.md +477 -0
- package/dist/knowledge/skills/website-section-stats/SKILL.md +1086 -0
- package/dist/knowledge/skills/website-section-stats/references/define-website-section-api.md +679 -0
- package/dist/knowledge/skills/website-section-stats/references/framework-website-stats-api.md +517 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +183 -67
- package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +575 -57
- package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +1 -1
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +6 -94
- package/dist/knowledge/skills/website-theme-authoring/SKILL.md +226 -0
- package/dist/knowledge/skills/website-theme-authoring/references/framework-website-theme-api.md +893 -0
- package/dist/knowledge/skills/worker-authoring/references/framework-worker-init-contract.md +4 -2
- package/dist/knowledge/topic-index.json +16442 -8572
- package/package.json +4 -4
- package/dist/knowledge/references/example.organizations.serves-as-provider.md +0 -12
- package/dist/knowledge/references/saas.models.organizations.service-provider-activity-feed.md +0 -121
- package/dist/knowledge/references/saas.models.organizations.service-provider-client-controls.md +0 -49
- package/dist/knowledge/references/saas.models.organizations.service-provider-relationships.md +0 -567
- package/dist/knowledge/references/saas.website.root-config.navigation.md +0 -37
- package/dist/knowledge/skills/service-provider-relationships/SKILL.md +0 -455
- package/dist/knowledge/skills/service-provider-relationships/references/framework-organization-types-api.md +0 -270
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-activity-feed-api.md +0 -129
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-capability-grants-api.md +0 -161
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-client-authentication-api.md +0 -224
- package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-relationships-api.md +0 -576
|
@@ -8,7 +8,7 @@ current contract — never a hand-mirrored copy.
|
|
|
8
8
|
## Frontmatter schema
|
|
9
9
|
|
|
10
10
|
The Zod 4 schema every MDX file's frontmatter is validated against
|
|
11
|
-
at render time
|
|
11
|
+
at render time. Field-level rationale (why `title` /
|
|
12
12
|
`summary` are raw strings instead of label keys, why `slug` is
|
|
13
13
|
branded, why `publishedAt` is stored as ISO-string rather than
|
|
14
14
|
`Date`) lives in the JSDoc.
|
|
@@ -21,13 +21,27 @@ branded, why `publishedAt` is stored as ISO-string rather than
|
|
|
21
21
|
|
|
22
22
|
### Origin Package: `@wildo-ai/saas-website`
|
|
23
23
|
|
|
24
|
+
```typescript
|
|
25
|
+
/**
|
|
26
|
+
* Where a website's posts live, relative to its root: one folder per locale, named by its segment
|
|
27
|
+
* (`languagePathSegment`: `fr`, `en-gb`), `src/content/blog/<segment>/<file>.mdx`. The blog collection loads from here, and `wildo website look` reads the same
|
|
28
|
+
* folder to open each post, so both find the same posts.
|
|
29
|
+
*/
|
|
30
|
+
export const WEBSITE_BLOG_CONTENT_BASE = './src/content/blog';
|
|
31
|
+
|
|
32
|
+
/** The posts the collection loads, relative to `WEBSITE_BLOG_CONTENT_BASE`: an `.mdx` file in a locale folder. */
|
|
33
|
+
export const WEBSITE_BLOG_CONTENT_PATTERN = '*/*.mdx';
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
37
|
+
|
|
24
38
|
```typescript
|
|
25
39
|
*
|
|
26
40
|
* `BlogPostFrontmatter` — the YAML frontmatter contract every blog
|
|
27
41
|
* post MDX file under `examples/<app>/website/src/content/blog/<locale>/`
|
|
28
42
|
* MUST satisfy.
|
|
29
43
|
*
|
|
30
|
-
* **
|
|
44
|
+
* **Context**: blogs are authored as full per-locale MDX files
|
|
31
45
|
* (one MDX per (slug, locale) pair), NOT as label-pack-keyed content.
|
|
32
46
|
* The frontmatter therefore carries strings directly (`title`,
|
|
33
47
|
* `summary`) rather than label keys — there is no shared
|
|
@@ -55,13 +69,41 @@ branded, why `publishedAt` is stored as ISO-string rather than
|
|
|
55
69
|
* parsers preserve the original string and the SEO emitters need
|
|
56
70
|
* the original ISO formatting (no Date.toISOString() round-trip
|
|
57
71
|
* loss).
|
|
58
|
-
* - `authorRef` — REQUIRED. Identifier of the author
|
|
59
|
-
*
|
|
60
|
-
*
|
|
72
|
+
* - `authorRef` — REQUIRED. Identifier of the author, declared with its
|
|
73
|
+
* kind in the site's blog vocabulary (`WebsiteBlogVocabulary.authors`) and
|
|
74
|
+
* shown by its words, never as the ref. Brand keeps it distinct from
|
|
75
|
+
* page/section refs.
|
|
61
76
|
* - `tags` — REQUIRED, possibly empty. Lowercase kebab-case tag
|
|
62
77
|
* identifiers. Drives `og:article:tag` and the listing-page facets.
|
|
63
|
-
* - `coverImageUrl` — OPTIONAL.
|
|
64
|
-
* and `og:image
|
|
78
|
+
* - `coverImageUrl` — OPTIONAL. The post's cover — its hero image, its
|
|
79
|
+
* index card and its `og:image` — as an absolute URL (a CDN) or as a
|
|
80
|
+
* path on the site itself (`/blog/covers/launch.png`, served from the
|
|
81
|
+
* site's `public/`). Use a raster image (PNG or JPEG): link previews read
|
|
82
|
+
* it through `og:image`, and an SVG there commonly shows no preview. A site path is what most sites have; the head
|
|
83
|
+
* renderer resolves it against the site's public origin wherever an
|
|
84
|
+
* absolute URL is required (`og:image`, the JSON-LD `image`).
|
|
85
|
+
* - `coverImageWidth` / `coverImageHeight` — the size of a cover the build
|
|
86
|
+
* cannot open, so REQUIRED together for an absolute-URL cover and refused
|
|
87
|
+
* for a site path. A cover is rendered through `WebsiteImage`, whose
|
|
88
|
+
* `width` and `height` let the browser reserve its space before it loads,
|
|
89
|
+
* so every cover needs a size. A site-path cover's size is MEASURED from
|
|
90
|
+
* its file in the site's `public/` by `resolveWebsiteBlogPostCover`
|
|
91
|
+
* (`@wildo-ai/saas-website/astro`), so a declared size there would be a
|
|
92
|
+
* second source that drifts the day the image is replaced. A remote image
|
|
93
|
+
* has no file the build can read (and the build does not fetch it), so
|
|
94
|
+
* its author states it. Astro's own `<Image />` infers a size for an image
|
|
95
|
+
* imported from `src/`, and for a remote image when asked to (`inferSize`,
|
|
96
|
+
* `inferRemoteSize()`), and requires `width` and `height` for an image in
|
|
97
|
+
* `public/`, "as Astro is unable to analyze these files". A cover is a
|
|
98
|
+
* `public/` URL in frontmatter that this build can still open, so it
|
|
99
|
+
* measures it rather than asks: one step past Astro.
|
|
100
|
+
* spec-cite: https://docs.astro.build/en/reference/modules/astro-assets/ —
|
|
101
|
+
* `<Image />`, "width and height (required for images in public/)".
|
|
102
|
+
*
|
|
103
|
+
* The schema carries a cross-field refinement, so Zod 4 refuses `.pick()`,
|
|
104
|
+
* `.omit()` and `.partial()` on it, and `.extend()` cannot remove a field: to
|
|
105
|
+
* derive a narrower schema, build a new `z.object` from the fields of
|
|
106
|
+
* `BlogPostFrontmatterSchema.shape` it needs.
|
|
65
107
|
*
|
|
66
108
|
* **Why a separate file from the page-manifest**: a blog post is NOT
|
|
67
109
|
* a `WebsitePageManifest` (no React `pageComponent` to mount — the
|
|
@@ -111,6 +153,18 @@ export const BlogPostTagSchema: typeof _BlogPostTagSchema = _BlogPostTagSchema;
|
|
|
111
153
|
|
|
112
154
|
export type BlogPostTag = z.infer<typeof _BlogPostTagSchema>;
|
|
113
155
|
|
|
156
|
+
/**
|
|
157
|
+
* A cover served by the site itself: one leading slash, never two (`//host/x` is a protocol-relative URL to another
|
|
158
|
+
* host). The one definition of "a site path" for a cover — the schema's refinement and the build's measurement both
|
|
159
|
+
* read it, so they cannot disagree about which covers are measured.
|
|
160
|
+
*/
|
|
161
|
+
export const BLOG_POST_COVER_SITE_PATH_PATTERN: RegExp = /^\/(?!\/)[^\s]*$/;
|
|
162
|
+
|
|
163
|
+
/** Whether a cover URL names a file on the site (measured at build) rather than a remote image (sized by its author). */
|
|
164
|
+
export function isBlogPostCoverSitePath(coverImageUrl: string): boolean {
|
|
165
|
+
return BLOG_POST_COVER_SITE_PATH_PATTERN.test(coverImageUrl);
|
|
166
|
+
}
|
|
167
|
+
|
|
114
168
|
const _BlogPostFrontmatterSchema = z.object({
|
|
115
169
|
title: z.string().min(1, { error: 'title must not be empty' }).max(200, { error: 'title must be at most 200 characters' }),
|
|
116
170
|
summary: z.string().min(1, { error: 'summary must not be empty' }).max(400, { error: 'summary must be at most 400 characters' }),
|
|
@@ -119,7 +173,50 @@ const _BlogPostFrontmatterSchema = z.object({
|
|
|
119
173
|
publishedAt: z.iso.datetime({ error: 'publishedAt must be an ISO-8601 datetime string' }),
|
|
120
174
|
authorRef: _BlogAuthorRefSchema,
|
|
121
175
|
tags: z.array(_BlogPostTagSchema),
|
|
122
|
-
coverImageUrl: z
|
|
176
|
+
coverImageUrl: z
|
|
177
|
+
.union([
|
|
178
|
+
z.url(),
|
|
179
|
+
// A path on the site: one leading slash, never two (`//host/x` is a protocol-relative URL to another host).
|
|
180
|
+
z.string().regex(BLOG_POST_COVER_SITE_PATH_PATTERN),
|
|
181
|
+
], { error: 'coverImageUrl must be an absolute URL or a site path starting with "/"' })
|
|
182
|
+
.optional(),
|
|
183
|
+
coverImageWidth: z.int({ error: 'coverImageWidth must be a whole number of pixels' }).positive().optional(),
|
|
184
|
+
coverImageHeight: z.int({ error: 'coverImageHeight must be a whole number of pixels' }).positive().optional(),
|
|
185
|
+
}).superRefine((frontmatter, ctx) => {
|
|
186
|
+
const declaresSize = frontmatter.coverImageWidth !== undefined || frontmatter.coverImageHeight !== undefined;
|
|
187
|
+
if (frontmatter.coverImageUrl === undefined) {
|
|
188
|
+
if (declaresSize) {
|
|
189
|
+
ctx.addIssue({
|
|
190
|
+
code: 'custom',
|
|
191
|
+
path: ['coverImageWidth'],
|
|
192
|
+
message: 'coverImageWidth / coverImageHeight give the size of a cover, and this post has no coverImageUrl.',
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
if (isBlogPostCoverSitePath(frontmatter.coverImageUrl)) {
|
|
198
|
+
if (declaresSize) {
|
|
199
|
+
ctx.addIssue({
|
|
200
|
+
code: 'custom',
|
|
201
|
+
path: ['coverImageWidth'],
|
|
202
|
+
message:
|
|
203
|
+
`The cover "${frontmatter.coverImageUrl}" is a file on the site, so its size is measured from that file. `
|
|
204
|
+
+ 'Remove coverImageWidth / coverImageHeight.',
|
|
205
|
+
});
|
|
206
|
+
}
|
|
207
|
+
return;
|
|
208
|
+
}
|
|
209
|
+
for (const [field, value] of [['coverImageWidth', frontmatter.coverImageWidth], ['coverImageHeight', frontmatter.coverImageHeight]] as const) {
|
|
210
|
+
if (value === undefined) {
|
|
211
|
+
ctx.addIssue({
|
|
212
|
+
code: 'custom',
|
|
213
|
+
path: [field],
|
|
214
|
+
message:
|
|
215
|
+
`The cover "${frontmatter.coverImageUrl}" is not a file on the site, so the build cannot measure it. `
|
|
216
|
+
+ 'Give its size in pixels with coverImageWidth and coverImageHeight.',
|
|
217
|
+
});
|
|
218
|
+
}
|
|
219
|
+
}
|
|
123
220
|
});
|
|
124
221
|
|
|
125
222
|
export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
|
|
@@ -128,6 +225,143 @@ export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
|
|
|
128
225
|
export type BlogPostFrontmatter = z.infer<typeof _BlogPostFrontmatterSchema>;
|
|
129
226
|
```
|
|
130
227
|
|
|
228
|
+
## A post's cover and its size — `resolveWebsiteBlogPostCover`
|
|
229
|
+
|
|
230
|
+
A cover is drawn through `WebsiteImage`, which needs its `width` and `height`. A cover the site serves (a site path,
|
|
231
|
+
a file in `public/`) is measured at build time from the file; a remote cover declares `coverImageWidth` /
|
|
232
|
+
`coverImageHeight` in its frontmatter. The route resolves it once in its `.astro` frontmatter
|
|
233
|
+
(`@wildo-ai/saas-website/astro`) and passes the result to the bridge island as `cover`; `<BlogPost>` refuses a cover
|
|
234
|
+
it was given no size for. `buildWebsiteBlogIndex` resolves every listed post's cover the same way.
|
|
235
|
+
|
|
236
|
+
## Import Origins
|
|
237
|
+
|
|
238
|
+
- `@wildo-ai/saas-website`
|
|
239
|
+
|
|
240
|
+
## Source Excerpts
|
|
241
|
+
|
|
242
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
*
|
|
246
|
+
* `WebsiteBlogPostCover` — a post's cover as the page renders it: its source and its size in pixels.
|
|
247
|
+
*
|
|
248
|
+
* The frontmatter names a cover by URL (`coverImageUrl`). Rendering it needs its size too, because a cover is drawn
|
|
249
|
+
* through `WebsiteImage`, whose `width` and `height` let the browser reserve the image's space before it loads. The
|
|
250
|
+
* size is resolved at build time, on the Node side, by `resolveWebsiteBlogPostCover` (`@wildo-ai/saas-website/astro`):
|
|
251
|
+
* measured from the file for a cover the site serves, read from `coverImageWidth` / `coverImageHeight` for a remote
|
|
252
|
+
* one. The resolved cover then reaches every surface that draws it:
|
|
253
|
+
*
|
|
254
|
+
* - the post's own page, through its bridge island's `cover` prop into `<BlogPost>`;
|
|
255
|
+
* - a blog listing, through `WebsiteBlogIndexEntry.cover` (`buildWebsiteBlogIndex` resolves each one).
|
|
256
|
+
*
|
|
257
|
+
* So no site has to assume a ratio for its covers in CSS or in a card.
|
|
258
|
+
*/
|
|
259
|
+
const _WebsiteBlogPostCoverSchema = z.strictObject({
|
|
260
|
+
/** The frontmatter's `coverImageUrl`, unchanged: a site path (`/blog/covers/launch.png`) or an absolute URL. */
|
|
261
|
+
src: z.string().min(1, { error: "A cover has a source." }),
|
|
262
|
+
/** The image's width in CSS pixels, as it is displayed (an EXIF-rotated photo is measured upright). */
|
|
263
|
+
width: z.int({ error: "A cover width is a whole number of pixels." }).positive(),
|
|
264
|
+
/** The image's height in CSS pixels, as it is displayed. */
|
|
265
|
+
height: z.int({ error: "A cover height is a whole number of pixels." }).positive(),
|
|
266
|
+
});
|
|
267
|
+
|
|
268
|
+
export const WebsiteBlogPostCoverSchema: typeof _WebsiteBlogPostCoverSchema = _WebsiteBlogPostCoverSchema;
|
|
269
|
+
|
|
270
|
+
export type WebsiteBlogPostCover = z.infer<typeof _WebsiteBlogPostCoverSchema>;
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Import Origins
|
|
274
|
+
|
|
275
|
+
- `@wildo-ai/saas-website`
|
|
276
|
+
|
|
277
|
+
## Source Excerpts
|
|
278
|
+
|
|
279
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
*
|
|
283
|
+
* `resolveWebsiteBlogPostCover(frontmatter, options?)` — a post's cover with its size, at build time.
|
|
284
|
+
*
|
|
285
|
+
* A cover is drawn through `WebsiteImage`, which needs `width` and `height` so the browser reserves its space before
|
|
286
|
+
* the image arrives. Where that size comes from depends on where the image lives:
|
|
287
|
+
*
|
|
288
|
+
* - **A cover the site serves** (`coverImageUrl: /blog/covers/launch.png`, a file in the site's `public/`) is
|
|
289
|
+
* MEASURED from that file, here, with `sharp`. Nobody types its size, so it cannot drift from the image the day the
|
|
290
|
+
* image is replaced; the frontmatter refuses a declared one.
|
|
291
|
+
* - **A remote cover** (`https://cdn.example.com/…`) has no file the build can open, so its author declares
|
|
292
|
+
* `coverImageWidth` and `coverImageHeight` in the frontmatter, and the schema requires both.
|
|
293
|
+
*
|
|
294
|
+
* Astro's own `<Image />` infers a size for an image imported from `src/`, and for a remote image when asked to
|
|
295
|
+
* (`inferSize`, `inferRemoteSize()`, which fetch it), and requires `width` and `height` for an image in `public/`, "as
|
|
296
|
+
* Astro is unable to analyze these files". A cover is named by a `public/` URL in frontmatter, and this build can still
|
|
297
|
+
* open that file, so it measures it rather than asking: one step past Astro. A remote cover is not fetched; its author
|
|
298
|
+
* states its size.
|
|
299
|
+
* spec-cite: https://docs.astro.build/en/reference/modules/astro-assets/ — `<Image />`, "width and height (required
|
|
300
|
+
* for images in public/)".
|
|
301
|
+
*
|
|
302
|
+
* Returns `undefined` for a post without a cover. Call it in the `.astro` frontmatter, which runs on Node during the
|
|
303
|
+
* build, and hand the result on: to the post's bridge island as `cover`, and nowhere else by hand —
|
|
304
|
+
* `buildWebsiteBlogIndex` calls it for every post it lists.
|
|
305
|
+
*
|
|
306
|
+
* @example
|
|
307
|
+
* const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
|
|
308
|
+
* const cover = await resolveWebsiteBlogPostCover(frontmatter);
|
|
309
|
+
* <BlogPostEnBridgeIsland client:load … cover={cover} />
|
|
310
|
+
*
|
|
311
|
+
* **The size is the image as displayed**: an EXIF-rotated photo is measured upright and an animated image by one
|
|
312
|
+
* frame, which is how a browser draws them (the same rule as the backend's uploaded-image analyzer).
|
|
313
|
+
*
|
|
314
|
+
* **It refuses rather than guesses.** A site path naming no file, a file outside `public/`, an image whose header
|
|
315
|
+
* gives no size, or a build where `sharp` cannot load all throw a `[blog-post-cover]` error naming the post's cover.
|
|
316
|
+
* A cover drawn at an invented size is the defect this exists to remove.
|
|
317
|
+
*
|
|
318
|
+
* `sharp` is loaded on the first site-path cover and only then, so a site whose covers are all remote never loads
|
|
319
|
+
* the native library.
|
|
320
|
+
*/
|
|
321
|
+
export interface ResolveWebsiteBlogPostCoverOptions {
|
|
322
|
+
/**
|
|
323
|
+
* The directory the site serves its own files from, resolved against the build's working directory (the site root,
|
|
324
|
+
* where Astro runs). Defaults to Astro's own default, `WEBSITE_PUBLIC_DIR`. Set it only when the site's Astro config
|
|
325
|
+
* sets `publicDir`.
|
|
326
|
+
*/
|
|
327
|
+
readonly publicDir?: string;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/** Where an Astro site serves its own files from, relative to the site root: Astro's default `publicDir`. */
|
|
331
|
+
export const WEBSITE_PUBLIC_DIR = "./public";
|
|
332
|
+
|
|
333
|
+
export async function resolveWebsiteBlogPostCover(
|
|
334
|
+
frontmatter: BlogPostFrontmatter,
|
|
335
|
+
options: ResolveWebsiteBlogPostCoverOptions = {},
|
|
336
|
+
): Promise<WebsiteBlogPostCover | undefined> {
|
|
337
|
+
const src = frontmatter.coverImageUrl;
|
|
338
|
+
if (src === undefined) return undefined;
|
|
339
|
+
if (!isBlogPostCoverSitePath(src)) {
|
|
340
|
+
const { coverImageWidth: width, coverImageHeight: height } = frontmatter;
|
|
341
|
+
if (width === undefined || height === undefined) {
|
|
342
|
+
throw new Error(
|
|
343
|
+
`[blog-post-cover] The remote cover "${src}" of post "${frontmatter.slug}" (${frontmatter.locale}) has no size. ` +
|
|
344
|
+
"Parse the frontmatter with parseBlogPostFrontmatter first: it requires coverImageWidth and coverImageHeight " +
|
|
345
|
+
"for a cover that is not a file on the site.",
|
|
346
|
+
);
|
|
347
|
+
}
|
|
348
|
+
return { src, width, height };
|
|
349
|
+
}
|
|
350
|
+
const file = resolveCoverFile(src, frontmatter, resolve(options.publicDir ?? WEBSITE_PUBLIC_DIR));
|
|
351
|
+
let size: { width: number; height: number };
|
|
352
|
+
try {
|
|
353
|
+
size = await measureImageFile(file);
|
|
354
|
+
} catch (error) {
|
|
355
|
+
// The measurement is shared by every post naming this file, so its error names the file and each post adds itself.
|
|
356
|
+
throw new Error(
|
|
357
|
+
`[blog-post-cover] The cover "${src}" of post "${frontmatter.slug}" (${frontmatter.locale}): ` +
|
|
358
|
+
`${error instanceof Error ? error.message : String(error)}`,
|
|
359
|
+
);
|
|
360
|
+
}
|
|
361
|
+
return { src, width: size.width, height: size.height };
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
131
365
|
## `<BlogPost>` — per-post page renderer
|
|
132
366
|
|
|
133
367
|
The single per-post page renderer the framework ships. Strict-
|
|
@@ -153,17 +387,18 @@ every other section uses.
|
|
|
153
387
|
* # What it does, end-to-end
|
|
154
388
|
*
|
|
155
389
|
* 1. **Strict frontmatter parse.** Reads the raw `entry.data` Astro
|
|
156
|
-
* hands the page (passthrough at the content-collection layer
|
|
157
|
-
*
|
|
390
|
+
* hands the page (passthrough at the content-collection layer, see
|
|
391
|
+
* `blog-post-collection.config.ts`) and runs it
|
|
158
392
|
* through `BlogPostFrontmatterSchema` (Zod 4) — branded `slug` /
|
|
159
393
|
* `authorRef` / `tags`, ISO-8601 `publishedAt`, optional
|
|
160
|
-
* `coverImageUrl
|
|
394
|
+
* `coverImageUrl` (sized by `coverImageWidth` / `coverImageHeight`
|
|
395
|
+
* when remote). A failure throws synchronously with a
|
|
161
396
|
* `[blog-post] (source="…")` message; Astro halts the build and
|
|
162
397
|
* points the operator to the offending MDX file.
|
|
163
398
|
* 2. **Renders `<WebsitePageLayout>` with a stable blog-post page
|
|
164
399
|
* ref.** The framework reserves `'blog-post'` as the
|
|
165
|
-
* `WebsitePageRef` for every blog post (see `BLOG_POST_PAGE_REF
|
|
166
|
-
*
|
|
400
|
+
* `WebsitePageRef` for every blog post (see `BLOG_POST_PAGE_REF`,
|
|
401
|
+
* in the blog vocabulary, for the rationale). All blog posts share one page ref
|
|
167
402
|
* because the SECTION ref under that page is what's
|
|
168
403
|
* blog-author-controlled (see point 3) — the page-level chrome,
|
|
169
404
|
* label scope, and analytics signal are the same across the entire
|
|
@@ -175,12 +410,22 @@ every other section uses.
|
|
|
175
410
|
* map for the duration of the render and ONLY the duration of the
|
|
176
411
|
* render, so two blog posts on the same site can ship different
|
|
177
412
|
* provider configs without leaking.
|
|
178
|
-
* 4. **Emits a hero block (title / summary / publish date / author
|
|
179
|
-
*
|
|
180
|
-
* to the MDX body.
|
|
181
|
-
*
|
|
182
|
-
*
|
|
183
|
-
*
|
|
413
|
+
* 4. **Emits a hero block (title / summary / publish date / author /
|
|
414
|
+
* tags / cover image)** from the parsed frontmatter, then yields
|
|
415
|
+
* to the MDX body. The cover is drawn through `WebsiteImage` at the
|
|
416
|
+
* size the route resolved at build time (`cover`, from
|
|
417
|
+
* `resolveWebsiteBlogPostCover`), so the browser reserves its space
|
|
418
|
+
* and a site's image styling reaches it; a post whose frontmatter
|
|
419
|
+
* names a cover and that was handed no size is refused. The date is written for the page's locale
|
|
420
|
+
* (`formatWebsitePublicationDate`); the author and every tag are
|
|
421
|
+
* shown by their WORDS, the chrome labels their refs name
|
|
422
|
+
* (`websiteBlogAuthorLabelKey` / `websiteBlogTagLabelKey`), never
|
|
423
|
+
* as the refs themselves. The engine's blocks stylesheet draws the
|
|
424
|
+
* article from the theme (the reading measure, the title at the
|
|
425
|
+
* section heading's size, the opening, the prose's headings, lists
|
|
426
|
+
* and tables); a site adjusts it through
|
|
427
|
+
* `article[data-website-blog-post-slug]` and the
|
|
428
|
+
* `data-website-blog-post-*` hooks, like any block.
|
|
184
429
|
*
|
|
185
430
|
* # Why a blog-specific page renderer (vs. the generic page bridge)
|
|
186
431
|
*
|
|
@@ -215,61 +460,21 @@ every other section uses.
|
|
|
215
460
|
*
|
|
216
461
|
* # Hydration + bundle boundary
|
|
217
462
|
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
* `<
|
|
223
|
-
*
|
|
224
|
-
*
|
|
463
|
+
* A site does not render `<BlogPost>` itself. The blog bridge island
|
|
464
|
+
* (`createWebsiteBlogPostBridgeIsland`, `@wildo-ai/saas-website/mdx`)
|
|
465
|
+
* renders it, with the post's compiled MDX body as its children, inside
|
|
466
|
+
* ONE React island, so the `mdxComponents` the body embeds resolve against
|
|
467
|
+
* `<WebsiteMdxProvider>`. Rendering `<BlogPost>` from an `.astro` file with
|
|
468
|
+
* `<Content />` children would lose that provider: Astro renders the
|
|
469
|
+
* children of a React component separately. The factory's preamble shows
|
|
470
|
+
* the per-locale bridge and the `[slug].astro` route shell, which also
|
|
471
|
+
* resolves the cover's size and passes it as the island's `cover`.
|
|
472
|
+
*
|
|
473
|
+
* The MDX runtime (`@mdx-js/react`) is React-only and pulls into the
|
|
474
|
+
* React island bundle — bundle-isolation tests walk `mdx.ts` as their own
|
|
225
475
|
* entry to keep the browser-facing closure auditable.
|
|
226
|
-
*
|
|
227
|
-
* Authoring example:
|
|
228
|
-
*
|
|
229
|
-
* ```astro
|
|
230
|
-
* ---
|
|
231
|
-
* // src/pages/blog/[slug].astro
|
|
232
|
-
* import { getCollection, getEntry } from 'astro:content';
|
|
233
|
-
* import { BlogPost } from '@wildo-ai/saas-website/mdx';
|
|
234
|
-
* import { BLOG_POST_MDX_COMPONENTS } from '@/blog/mdx-components';
|
|
235
|
-
*
|
|
236
|
-
* export async function getStaticPaths() {
|
|
237
|
-
* const posts = await getCollection('blog');
|
|
238
|
-
* return posts
|
|
239
|
-
* .filter((p) => p.data.locale === 'en')
|
|
240
|
-
* .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
|
|
241
|
-
* }
|
|
242
|
-
*
|
|
243
|
-
* const { entry } = Astro.props;
|
|
244
|
-
* const { Content } = await entry.render();
|
|
245
|
-
* ---
|
|
246
|
-
* <BlogPost
|
|
247
|
-
* rawFrontmatter={entry.data}
|
|
248
|
-
* source={entry.id}
|
|
249
|
-
* mdxComponents={BLOG_POST_MDX_COMPONENTS}
|
|
250
|
-
* client:load
|
|
251
|
-
* >
|
|
252
|
-
* <Content />
|
|
253
|
-
* </BlogPost>
|
|
254
|
-
* ```
|
|
255
476
|
*/
|
|
256
477
|
|
|
257
|
-
/**
|
|
258
|
-
* Reserved `WebsitePageRef` for every blog post page. Exported so
|
|
259
|
-
* consumers can register a matching `BLOG_POST_PAGE_MANIFEST` in
|
|
260
|
-
* their site root config (the page manifest carries the navigation
|
|
261
|
-
* + label-pack scope; the renderer carries the structural layout).
|
|
262
|
-
*
|
|
263
|
-
* Branded as a plain string literal (cast through `unknown`) because:
|
|
264
|
-
* - The `WebsitePageRef` brand is enforced via Zod's `.brand<>()`,
|
|
265
|
-
* and parsing a string literal at module load time would require
|
|
266
|
-
* dragging the Zod runtime into module init — gratuitous when the
|
|
267
|
-
* ref is a compile-time constant.
|
|
268
|
-
* - `WebsitePageLayout` re-parses any incoming `pageRef` string
|
|
269
|
-
* defensively (see `WebsitePageLayoutProps.pageRef` JSDoc), so the
|
|
270
|
-
* brand is re-asserted at render time anyway.
|
|
271
|
-
*/
|
|
272
|
-
export const BLOG_POST_PAGE_REF: WebsitePageRef = 'blog-post' as unknown as WebsitePageRef;
|
|
273
478
|
|
|
274
479
|
export interface BlogPostProps {
|
|
275
480
|
/**
|
|
@@ -301,6 +506,11 @@ export interface BlogPostProps {
|
|
|
301
506
|
* (no embedded React) needs no overrides.
|
|
302
507
|
*/
|
|
303
508
|
mdxComponents?: WebsiteMdxComponentsMap;
|
|
509
|
+
/**
|
|
510
|
+
* The post's route, `/blog/<slug>`, forwarded to `<WebsitePageLayout>` so the server-rendered header knows the
|
|
511
|
+
* current page (see `WebsitePageLayoutProps.routePath`).
|
|
512
|
+
*/
|
|
513
|
+
routePath?: string;
|
|
304
514
|
/**
|
|
305
515
|
* Per-page chrome overrides forwarded straight into
|
|
306
516
|
* `<WebsitePageLayout>`. `null` suppresses the slot entirely;
|
|
@@ -311,10 +521,18 @@ export interface BlogPostProps {
|
|
|
311
521
|
header?: ReactNode | null;
|
|
312
522
|
footer?: ReactNode | null;
|
|
313
523
|
/**
|
|
314
|
-
* The
|
|
315
|
-
* `
|
|
316
|
-
*
|
|
317
|
-
*
|
|
524
|
+
* The post's cover with its size, resolved at build time by
|
|
525
|
+
* `resolveWebsiteBlogPostCover` (`@wildo-ai/saas-website/astro`) in the
|
|
526
|
+
* route's `.astro` frontmatter and forwarded by the bridge island.
|
|
527
|
+
* Required exactly when the frontmatter names a cover, and its `src` must
|
|
528
|
+
* be that cover: the renderer refuses a cover it has no size for rather
|
|
529
|
+
* than drawing one at a guessed size.
|
|
530
|
+
*/
|
|
531
|
+
cover?: WebsiteBlogPostCover;
|
|
532
|
+
/**
|
|
533
|
+
* The compiled MDX body — the post's MDX module, which the bridge island
|
|
534
|
+
* renders here. Rendered inside the `<WebsiteMdxProvider>` boundary so its
|
|
535
|
+
* inline `<TagName />` references resolve against `mdxComponents`.
|
|
318
536
|
*/
|
|
319
537
|
children: ReactNode;
|
|
320
538
|
}
|
|
@@ -328,11 +546,52 @@ export interface BlogPostProps {
|
|
|
328
546
|
*/
|
|
329
547
|
const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
|
|
330
548
|
|
|
549
|
+
/**
|
|
550
|
+
* The cover to draw, checked against the frontmatter: `undefined` for a post without one; otherwise the resolved
|
|
551
|
+
* cover, whose source must be the frontmatter's. Refuses a cover it has no size for, a size for a post without a cover,
|
|
552
|
+
* and a size for a different image, each naming the remedy, because every one of them would draw a wrong picture.
|
|
553
|
+
*/
|
|
554
|
+
function coverToRender(frontmatter: BlogPostFrontmatter, cover: unknown, source: string | undefined): WebsiteBlogPostCover | undefined {
|
|
555
|
+
const sourceSuffix = source !== undefined ? ` (source="${source}")` : '';
|
|
556
|
+
if (frontmatter.coverImageUrl === undefined) {
|
|
557
|
+
if (cover !== undefined) {
|
|
558
|
+
throw new Error(`[blog-post] A cover was passed for a post whose frontmatter names none${sourceSuffix}.`);
|
|
559
|
+
}
|
|
560
|
+
return undefined;
|
|
561
|
+
}
|
|
562
|
+
if (cover === undefined) {
|
|
563
|
+
throw new Error(
|
|
564
|
+
`[blog-post] The frontmatter names the cover "${frontmatter.coverImageUrl}" and no size for it reached the renderer`
|
|
565
|
+
+ `${sourceSuffix}. Resolve it in the route's .astro frontmatter with \`await resolveWebsiteBlogPostCover(frontmatter)\``
|
|
566
|
+
+ ' (@wildo-ai/saas-website/astro) and pass it to the bridge island as `cover`.',
|
|
567
|
+
);
|
|
568
|
+
}
|
|
569
|
+
const parsed = WebsiteBlogPostCoverSchema.safeParse(cover);
|
|
570
|
+
if (!parsed.success) {
|
|
571
|
+
throw new Error(`[blog-post] The cover passed to the renderer is not a { src, width, height } cover${sourceSuffix}.`);
|
|
572
|
+
}
|
|
573
|
+
if (parsed.data.src !== frontmatter.coverImageUrl) {
|
|
574
|
+
throw new Error(
|
|
575
|
+
`[blog-post] The cover passed to the renderer is "${parsed.data.src}", and the frontmatter names "${frontmatter.coverImageUrl}"`
|
|
576
|
+
+ `${sourceSuffix}. Resolve the cover from this post's own frontmatter.`,
|
|
577
|
+
);
|
|
578
|
+
}
|
|
579
|
+
return parsed.data;
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
/** One tag, by its word: a component of its own so each tag reads its label through the hook. */
|
|
583
|
+
function BlogPostTag({ tag }: { tag: string }): ReactNode {
|
|
584
|
+
return <li>{useWebsiteLabelByKey(websiteBlogTagLabelKey(tag))}</li>;
|
|
585
|
+
}
|
|
586
|
+
BlogPostTag.displayName = 'BlogPostTag';
|
|
587
|
+
|
|
331
588
|
export function BlogPost(props: BlogPostProps): ReactNode {
|
|
332
589
|
const {
|
|
333
590
|
rawFrontmatter,
|
|
334
591
|
source,
|
|
335
592
|
mdxComponents = EMPTY_MDX_COMPONENTS,
|
|
593
|
+
routePath,
|
|
594
|
+
cover: rawCover,
|
|
336
595
|
header,
|
|
337
596
|
footer,
|
|
338
597
|
children,
|
|
@@ -349,30 +608,37 @@ export function BlogPost(props: BlogPostProps): ReactNode {
|
|
|
349
608
|
const parseCtx: ParseBlogPostFrontmatterContext =
|
|
350
609
|
source !== undefined ? { source } : {};
|
|
351
610
|
const frontmatter = parseBlogPostFrontmatter(rawFrontmatter, parseCtx);
|
|
611
|
+
const cover = coverToRender(frontmatter, rawCover, source);
|
|
612
|
+
const { locale } = useWebsiteRuntime();
|
|
613
|
+
const authorName = useWebsiteLabelByKey(websiteBlogAuthorLabelKey(frontmatter.authorRef));
|
|
352
614
|
|
|
353
615
|
/**
|
|
354
616
|
* The hero markup intentionally uses semantic HTML5 elements
|
|
355
617
|
* (`<header>`, `<h1>`, `<time>`, `<address>`) rather than raw
|
|
356
618
|
* `<div>`s so screen readers and crawlers see the post structure
|
|
357
|
-
* without consumer styling intervention.
|
|
358
|
-
*
|
|
359
|
-
*
|
|
619
|
+
* without consumer styling intervention. No CSS ships from this
|
|
620
|
+
* file: the article's look is the engine's blocks stylesheet
|
|
621
|
+
* (`website-blocks.styles.ts`, drawn from the theme), which the
|
|
622
|
+
* page layout renders, and a site's own rules adjust it.
|
|
360
623
|
*/
|
|
361
624
|
return (
|
|
362
625
|
<WebsitePageLayout
|
|
363
626
|
pageRef={BLOG_POST_PAGE_REF}
|
|
627
|
+
{...(routePath !== undefined ? { routePath } : {})}
|
|
364
628
|
header={header}
|
|
365
629
|
footer={footer}
|
|
366
630
|
>
|
|
367
|
-
<article data-website-blog-post-slug={frontmatter.slug
|
|
631
|
+
<article data-website-blog-post-slug={frontmatter.slug} data-website-prose="">
|
|
368
632
|
<header>
|
|
369
|
-
{
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
633
|
+
{/*
|
|
634
|
+
* The cover is decorative (`alt=""`): the title beside it says what the post is. Eager, because it is the
|
|
635
|
+
* first thing on the page. The wrapper carries the blog's styling hook; the image is the primitive, so a
|
|
636
|
+
* site's `[data-website-primitive="image"]` styling reaches it too.
|
|
637
|
+
*/}
|
|
638
|
+
{cover !== undefined ? (
|
|
639
|
+
<div data-website-blog-post-cover>
|
|
640
|
+
<WebsiteImage src={cover.src} alt="" width={cover.width} height={cover.height} loading="eager" />
|
|
641
|
+
</div>
|
|
376
642
|
) : null}
|
|
377
643
|
<h1>{frontmatter.title}</h1>
|
|
378
644
|
<p data-website-blog-post-summary>{frontmatter.summary}</p>
|
|
@@ -386,19 +652,15 @@ export function BlogPost(props: BlogPostProps): ReactNode {
|
|
|
386
652
|
*/}
|
|
387
653
|
<div data-website-blog-post-meta>
|
|
388
654
|
<time dateTime={frontmatter.publishedAt}>
|
|
389
|
-
{frontmatter.publishedAt}
|
|
655
|
+
{formatWebsitePublicationDate(frontmatter.publishedAt, locale)}
|
|
390
656
|
</time>
|
|
391
657
|
{' · '}
|
|
392
|
-
<address data-website-blog-post-author>
|
|
393
|
-
{frontmatter.authorRef as unknown as string}
|
|
394
|
-
</address>
|
|
658
|
+
<address data-website-blog-post-author>{authorName}</address>
|
|
395
659
|
</div>
|
|
396
660
|
{frontmatter.tags.length > 0 ? (
|
|
397
661
|
<ul data-website-blog-post-tags>
|
|
398
662
|
{frontmatter.tags.map((tag) => (
|
|
399
|
-
<
|
|
400
|
-
{tag as unknown as string}
|
|
401
|
-
</li>
|
|
663
|
+
<BlogPostTag key={tag} tag={tag} />
|
|
402
664
|
))}
|
|
403
665
|
</ul>
|
|
404
666
|
) : null}
|
|
@@ -535,7 +797,7 @@ WebsiteMdxProvider.displayName = 'WebsiteMdxProvider';
|
|
|
535
797
|
|
|
536
798
|
## `buildBlogPostCollectionConfig` + `parseBlogPostFrontmatter`
|
|
537
799
|
|
|
538
|
-
The
|
|
800
|
+
The bridge between Astro's bundled Zod 3 (in `astro:content`)
|
|
539
801
|
and the engine's canonical Zod 4 schema. The collection layer
|
|
540
802
|
accepts any frontmatter (passthrough); the strict validation runs
|
|
541
803
|
synchronously at render time inside `<BlogPost>` (and at build time
|
|
@@ -552,7 +814,7 @@ schema, no double source of truth).
|
|
|
552
814
|
|
|
553
815
|
```typescript
|
|
554
816
|
*
|
|
555
|
-
* Astro content-collection bridge for blog posts
|
|
817
|
+
* Astro content-collection bridge for blog posts.
|
|
556
818
|
*
|
|
557
819
|
* # The Zod-version bridge problem
|
|
558
820
|
*
|
|
@@ -562,21 +824,21 @@ schema, no double source of truth).
|
|
|
562
824
|
* a schema instance directly across the version boundary, and shimming
|
|
563
825
|
* a Zod 4 schema down to a Zod 3 schema would create either:
|
|
564
826
|
*
|
|
565
|
-
* - a hand-mirrored copy
|
|
827
|
+
* - a hand-mirrored copy — maintained in `src/content.config.ts`
|
|
566
828
|
* using Astro's `z`, with silent-drift risk every time a field is
|
|
567
829
|
* added/removed/refined; or
|
|
568
|
-
* - a runtime bridge package
|
|
830
|
+
* - a runtime bridge package — a non-trivial maintenance
|
|
569
831
|
* surface for a marginal gain.
|
|
570
832
|
*
|
|
571
|
-
*
|
|
572
|
-
* `src/content
|
|
833
|
+
* This file sidesteps the bridge entirely: the consumer's
|
|
834
|
+
* `src/content.config.ts` declares a `passthrough` collection schema
|
|
573
835
|
* that lets Astro accept any frontmatter shape; the engine then
|
|
574
836
|
* validates with the canonical Zod 4 schema at render time inside
|
|
575
837
|
* `<BlogPost>`. Astro's static site generator runs the page render
|
|
576
838
|
* during the build, so a malformed frontmatter still surfaces as a
|
|
577
839
|
* BUILD-TIME error (the `.parse()` call throws synchronously and Astro
|
|
578
|
-
* reports it with the page URL) — the only practical difference
|
|
579
|
-
*
|
|
840
|
+
* reports it with the page URL) — the only practical difference from a
|
|
841
|
+
* hand-mirrored schema is the error-message stack location.
|
|
580
842
|
*
|
|
581
843
|
* # Why the engine ships an opaque shape (rather than the consumer
|
|
582
844
|
* importing the Astro `z` directly)
|
|
@@ -588,29 +850,39 @@ schema, no double source of truth).
|
|
|
588
850
|
* the wiring in the engine means the framework absorbs the upgrade
|
|
589
851
|
* cost in ONE place when Astro bumps a major.
|
|
590
852
|
*
|
|
591
|
-
* The shape returned here is `{ schema
|
|
592
|
-
*
|
|
853
|
+
* The shape returned here is `{ loader, schema }`. The consumer spreads it
|
|
854
|
+
* into their `defineCollection` call, in `website/src/content.config.ts`
|
|
855
|
+
* (the file Astro 5+ reads; `src/content/config.ts` is the legacy path):
|
|
593
856
|
*
|
|
594
857
|
* ```ts
|
|
595
|
-
* //
|
|
858
|
+
* // website/src/content.config.ts
|
|
596
859
|
* import { defineCollection, z } from 'astro:content';
|
|
860
|
+
* import { glob } from 'astro/loaders';
|
|
597
861
|
* import { buildBlogPostCollectionConfig } from '@wildo-ai/saas-website/mdx';
|
|
598
862
|
*
|
|
599
863
|
* export const collections = {
|
|
600
|
-
* blog: defineCollection({
|
|
601
|
-
* type: 'content',
|
|
602
|
-
* ...buildBlogPostCollectionConfig({ astroZ: z }),
|
|
603
|
-
* }),
|
|
864
|
+
* blog: defineCollection({ ...buildBlogPostCollectionConfig({ astroZ: z, glob }) }),
|
|
604
865
|
* };
|
|
605
866
|
* ```
|
|
606
867
|
*
|
|
607
|
-
* The consumer passes Astro's own `z` in
|
|
608
|
-
* import `astro:content`
|
|
609
|
-
* the Astro build
|
|
610
|
-
*
|
|
611
|
-
*
|
|
612
|
-
*
|
|
613
|
-
*
|
|
868
|
+
* The consumer passes Astro's own `z` and `glob` in, because the engine
|
|
869
|
+
* cannot import `astro:content` (a virtual module that only exists inside
|
|
870
|
+
* the Astro build) nor `astro/loaders` (it would pull `astro` into the
|
|
871
|
+
* engine's walked closure, which the bundle-isolation test forbids). The
|
|
872
|
+
* engine builds the passthrough schema and the loader from them.
|
|
873
|
+
*
|
|
874
|
+
* **The upgrade this exists for happened (#2570).** The recipe used to be a
|
|
875
|
+
* legacy `type: 'content'` collection, and Astro 6 REMOVED legacy
|
|
876
|
+
* collections: the collection loaded empty, `getStaticPaths` emitted no post,
|
|
877
|
+
* and every post answered 404 while `astro check` and `wildo website audit`
|
|
878
|
+
* both passed. The loader is now the engine's, so the next Astro change lands
|
|
879
|
+
* here, once.
|
|
880
|
+
*
|
|
881
|
+
* **The entry id is the post's PATH, `<locale>/<file>`** (`blogPostEntryId`).
|
|
882
|
+
* Astro's default id is the frontmatter `slug` when present, and a post's
|
|
883
|
+
* translations share their slug by design (that is how the language switcher
|
|
884
|
+
* finds them), so the default made one locale's post silently overwrite the
|
|
885
|
+
* other's ("Later items with the same id will overwrite earlier ones").
|
|
614
886
|
*
|
|
615
887
|
* # `parseBlogPostFrontmatter`
|
|
616
888
|
*
|
|
@@ -643,18 +915,41 @@ export interface AstroZodFactoryShape {
|
|
|
643
915
|
};
|
|
644
916
|
}
|
|
645
917
|
|
|
918
|
+
/**
|
|
919
|
+
* Minimal contract for Astro's `glob` loader factory (`import { glob } from 'astro/loaders'`), typed structurally for
|
|
920
|
+
* the reason `AstroZodFactoryShape` is.
|
|
921
|
+
*/
|
|
922
|
+
export type AstroGlobLoaderFactoryShape = (options: {
|
|
923
|
+
readonly pattern: string;
|
|
924
|
+
readonly base: string;
|
|
925
|
+
readonly generateId: (options: { readonly entry: string; readonly data: Record<string, unknown> }) => string;
|
|
926
|
+
}) => unknown;
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* A post's collection id: its path under the blog folder without the extension, `en/launching-early-access`. Unique
|
|
930
|
+
* by construction (one file per path), where the frontmatter `slug` Astro would use by default is shared by a post's
|
|
931
|
+
* translations.
|
|
932
|
+
*/
|
|
933
|
+
export function blogPostEntryId(entry: string): string {
|
|
934
|
+
return entry.replace(/\.mdx$/u, '');
|
|
935
|
+
}
|
|
936
|
+
|
|
646
937
|
export interface BuildBlogPostCollectionConfigOptions {
|
|
647
938
|
/**
|
|
648
939
|
* Astro's bundled `z` object — pass `import { z } from 'astro:content'`
|
|
649
|
-
* from the consumer-side `src/content
|
|
940
|
+
* from the consumer-side `src/content.config.ts`. The engine cannot
|
|
650
941
|
* import `astro:content` itself (virtual module, only present inside
|
|
651
942
|
* the Astro build pipeline; would also bloat the bundle-isolation
|
|
652
943
|
* walked closure with the `astro` runtime).
|
|
653
944
|
*/
|
|
654
945
|
astroZ: AstroZodFactoryShape;
|
|
946
|
+
/** Astro's `glob` loader factory — pass `import { glob } from 'astro/loaders'`. */
|
|
947
|
+
glob: AstroGlobLoaderFactoryShape;
|
|
655
948
|
}
|
|
656
949
|
|
|
657
950
|
export interface BlogPostCollectionConfigShape {
|
|
951
|
+
/** The collection's loader: every post under `WEBSITE_BLOG_CONTENT_BASE`, each with its path as its id. */
|
|
952
|
+
loader: unknown;
|
|
658
953
|
/**
|
|
659
954
|
* The schema slot consumed by Astro's `defineCollection({...})`.
|
|
660
955
|
* A `passthrough` record (no field constraints at this layer) so
|
|
@@ -668,12 +963,31 @@ export interface BlogPostCollectionConfigShape {
|
|
|
668
963
|
export function buildBlogPostCollectionConfig(
|
|
669
964
|
opts: BuildBlogPostCollectionConfigOptions,
|
|
670
965
|
): BlogPostCollectionConfigShape {
|
|
671
|
-
const { astroZ } = opts;
|
|
966
|
+
const { astroZ, glob } = opts;
|
|
672
967
|
return {
|
|
968
|
+
loader: glob({ pattern: WEBSITE_BLOG_CONTENT_PATTERN, base: WEBSITE_BLOG_CONTENT_BASE, generateId: ({ entry }) => blogPostEntryId(entry) }),
|
|
673
969
|
schema: astroZ.object({}).passthrough(),
|
|
674
970
|
};
|
|
675
971
|
}
|
|
676
972
|
|
|
973
|
+
/**
|
|
974
|
+
* A frontmatter whose YAML timestamps arrived as `Date`s, with each one back as the ISO-8601 string its author wrote.
|
|
975
|
+
*
|
|
976
|
+
* Astro's content layer parses frontmatter with YAML 1.1 timestamps, so an unquoted `publishedAt:
|
|
977
|
+
* 2026-04-15T09:00:00.000Z` reaches the page as a `Date` (measured on Astro 6.1.8, #2570), where the legacy collection
|
|
978
|
+
* delivered the string. Both are the same instant, so a top-level `Date` is turned back into its ISO string before the
|
|
979
|
+
* strict schema, whose datetime fields are strings. Nothing else changes: an invalid value still fails, and a value
|
|
980
|
+
* that is not a `Date` is left exactly as it came.
|
|
981
|
+
*/
|
|
982
|
+
function withYamlTimestampsAsIsoStrings(raw: unknown): unknown {
|
|
983
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return raw;
|
|
984
|
+
const entries = Object.entries(raw as Record<string, unknown>);
|
|
985
|
+
if (!entries.some(([, value]) => value instanceof Date)) return raw;
|
|
986
|
+
return Object.fromEntries(
|
|
987
|
+
entries.map(([key, value]) => [key, value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : value]),
|
|
988
|
+
);
|
|
989
|
+
}
|
|
990
|
+
|
|
677
991
|
/**
|
|
678
992
|
* Strict Zod-4 validator for blog-post frontmatter. Called at the top
|
|
679
993
|
* of `<BlogPost>` rendering against `entry.data` (whatever Astro's
|
|
@@ -701,7 +1015,7 @@ export function parseBlogPostFrontmatter(
|
|
|
701
1015
|
raw: unknown,
|
|
702
1016
|
ctx: ParseBlogPostFrontmatterContext = {},
|
|
703
1017
|
): BlogPostFrontmatter {
|
|
704
|
-
const result = BlogPostFrontmatterSchema.safeParse(raw);
|
|
1018
|
+
const result = BlogPostFrontmatterSchema.safeParse(withYamlTimestampsAsIsoStrings(raw));
|
|
705
1019
|
if (result.success) {
|
|
706
1020
|
return result.data;
|
|
707
1021
|
}
|
|
@@ -721,13 +1035,20 @@ export function parseBlogPostFrontmatter(
|
|
|
721
1035
|
}
|
|
722
1036
|
```
|
|
723
1037
|
|
|
724
|
-
## `renderBlogPostHeadHtml` — per-post `<head>`
|
|
1038
|
+
## `renderBlogPostHeadHtml` and `buildBlogPostStructuredDataPayload` — per-post `<head>` and JSON-LD
|
|
725
1039
|
|
|
726
1040
|
Sibling of `renderWebsitePageHeadHtml`, but reads its title /
|
|
727
1041
|
description / OG image / `article:*` metadata from the validated
|
|
728
1042
|
`BlogPostFrontmatter` instead of the page manifest's
|
|
729
1043
|
`metaLabelKeys`. Emits `og:type=article` + the `article:published_time`
|
|
730
|
-
/ `article:author` / `article:tag` (one per tag) block
|
|
1044
|
+
/ `article:author` / `article:tag` (one per tag) block, and the post's
|
|
1045
|
+
`BlogPosting` JSON-LD. Both functions (from `@wildo-ai/saas-website/astro`)
|
|
1046
|
+
REQUIRE `words` — the post's author and tags as words, from
|
|
1047
|
+
`resolveWebsiteBlogPostWords({ authorRef, tags, vocabulary, labelPack })` —
|
|
1048
|
+
because what they publish is indexed by search engines and must never carry
|
|
1049
|
+
a ref. `buildBlogPostStructuredDataPayload` is what a site's
|
|
1050
|
+
`structured-data/page-payloads.ts` calls so `wildo website audit` sees each
|
|
1051
|
+
post's payload.
|
|
731
1052
|
|
|
732
1053
|
## Import Origins
|
|
733
1054
|
|
|
@@ -834,7 +1155,12 @@ export interface RenderBlogPostHeadHtmlOptions {
|
|
|
834
1155
|
*/
|
|
835
1156
|
frontmatter: BlogPostFrontmatter;
|
|
836
1157
|
/**
|
|
837
|
-
*
|
|
1158
|
+
* The post's author and tags as words — from `resolveWebsiteBlogPostWords` with the page's label pack. Published as
|
|
1159
|
+
* `article:author` / `article:tag` and in the JSON-LD; never the frontmatter's refs.
|
|
1160
|
+
*/
|
|
1161
|
+
words: WebsiteBlogPostWords;
|
|
1162
|
+
/**
|
|
1163
|
+
* AI-training opt-out — when `true`, the renderer emits
|
|
838
1164
|
* `<meta name="robots" content="noai, noimageai">`. The sibling
|
|
839
1165
|
* `_headers` entry is produced by `renderBlogPostNoaiHeaders()`
|
|
840
1166
|
* (one knob, two channels — see the page-head renderer's
|
|
@@ -854,16 +1180,29 @@ export interface RenderBlogPostHeadHtmlOptions {
|
|
|
854
1180
|
|
|
855
1181
|
export interface BuildBlogPostStructuredDataPayloadOptions {
|
|
856
1182
|
frontmatter: BlogPostFrontmatter;
|
|
1183
|
+
/**
|
|
1184
|
+
* The post's author and tags as words, from `resolveWebsiteBlogPostWords`. Never the frontmatter's refs: they are
|
|
1185
|
+
* identifiers, and this payload is published to every search engine.
|
|
1186
|
+
*/
|
|
1187
|
+
words: WebsiteBlogPostWords;
|
|
857
1188
|
canonicalUrl: string;
|
|
858
1189
|
siteOrigin: string;
|
|
859
1190
|
siteName: string;
|
|
860
1191
|
locale: AvailableLanguage;
|
|
861
1192
|
}
|
|
862
1193
|
|
|
1194
|
+
/**
|
|
1195
|
+
* The cover as an absolute URL, for the surfaces that require one (`og:image`, the JSON-LD `image`): a site path
|
|
1196
|
+
* (`/blog/covers/x.png`) is resolved against the site's public origin, an absolute URL is kept.
|
|
1197
|
+
*/
|
|
1198
|
+
export function resolveBlogPostCoverImageUrl(coverImageUrl: string, siteOrigin: string): string {
|
|
1199
|
+
return coverImageUrl.startsWith('/') ? `${siteOrigin.replace(/\/$/, '')}${coverImageUrl}` : coverImageUrl;
|
|
1200
|
+
}
|
|
1201
|
+
|
|
863
1202
|
export function buildBlogPostStructuredDataPayload(
|
|
864
1203
|
opts: BuildBlogPostStructuredDataPayloadOptions,
|
|
865
1204
|
): WebsiteStructuredDataPayload {
|
|
866
|
-
const { frontmatter, canonicalUrl, siteOrigin, siteName, locale } = opts;
|
|
1205
|
+
const { frontmatter, words, canonicalUrl, siteOrigin, siteName, locale } = opts;
|
|
867
1206
|
return {
|
|
868
1207
|
'@type': 'BlogPosting',
|
|
869
1208
|
'@id': `${canonicalUrl}#blog-post`,
|
|
@@ -871,8 +1210,8 @@ export function buildBlogPostStructuredDataPayload(
|
|
|
871
1210
|
description: frontmatter.summary,
|
|
872
1211
|
datePublished: frontmatter.publishedAt,
|
|
873
1212
|
author: {
|
|
874
|
-
'@type':
|
|
875
|
-
name:
|
|
1213
|
+
'@type': words.author.kind,
|
|
1214
|
+
name: words.author.name,
|
|
876
1215
|
},
|
|
877
1216
|
publisher: {
|
|
878
1217
|
'@type': 'Organization',
|
|
@@ -882,18 +1221,19 @@ export function buildBlogPostStructuredDataPayload(
|
|
|
882
1221
|
mainEntityOfPage: canonicalUrl,
|
|
883
1222
|
url: canonicalUrl,
|
|
884
1223
|
inLanguage: String(locale),
|
|
885
|
-
...(frontmatter.coverImageUrl ? { image: frontmatter.coverImageUrl } : {}),
|
|
886
|
-
...(
|
|
1224
|
+
...(frontmatter.coverImageUrl ? { image: resolveBlogPostCoverImageUrl(frontmatter.coverImageUrl, siteOrigin) } : {}),
|
|
1225
|
+
...(words.tags.length > 0 ? { keywords: words.tags.join(', ') } : {}),
|
|
887
1226
|
};
|
|
888
1227
|
}
|
|
889
1228
|
|
|
890
1229
|
export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): string {
|
|
891
|
-
const { siteContext, locale, routePath, frontmatter, noaiOptOut } = opts;
|
|
1230
|
+
const { siteContext, locale, routePath, frontmatter, words, noaiOptOut } = opts;
|
|
892
1231
|
const { rootConfig, websiteConfig } = siteContext;
|
|
893
1232
|
|
|
894
1233
|
const title = frontmatter.title;
|
|
895
1234
|
const description = frontmatter.summary;
|
|
896
|
-
const ogImageUrl =
|
|
1235
|
+
const ogImageUrl =
|
|
1236
|
+
frontmatter.coverImageUrl === undefined ? undefined : resolveBlogPostCoverImageUrl(frontmatter.coverImageUrl, websiteConfig.publicOrigin);
|
|
897
1237
|
const titleAttr = escapeHtmlAttribute(title);
|
|
898
1238
|
const descriptionAttr = escapeHtmlAttribute(description);
|
|
899
1239
|
const titleText = escapeHtmlText(title);
|
|
@@ -955,26 +1295,24 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
|
|
|
955
1295
|
* vertical defines:
|
|
956
1296
|
* - `article:published_time` (ISO-8601 — already validated by
|
|
957
1297
|
* the frontmatter schema's `z.iso.datetime`).
|
|
958
|
-
* - `article:author` (free text or URL — we emit the author
|
|
959
|
-
*
|
|
960
|
-
*
|
|
1298
|
+
* - `article:author` (free text or URL — we emit the author's
|
|
1299
|
+
* name, the words its label holds; a future author profile
|
|
1300
|
+
* page would let it carry that page's URL instead).
|
|
961
1301
|
* - `article:tag` (one tag per emission; the OG spec uses
|
|
962
1302
|
* repeated `<meta property="article:tag">` lines, NOT a
|
|
963
1303
|
* comma-joined list).
|
|
964
1304
|
*
|
|
965
1305
|
* `article:section` (the OG "section" field, e.g. "Engineering" /
|
|
966
|
-
* "Product") is intentionally NOT emitted —
|
|
967
|
-
* blog-section
|
|
968
|
-
*
|
|
1306
|
+
* "Product") is intentionally NOT emitted — the frontmatter has no
|
|
1307
|
+
* blog-section field, and emitting an empty section would be worse
|
|
1308
|
+
* than omission.
|
|
969
1309
|
*/
|
|
970
1310
|
const articleMetaLines: string[] = [
|
|
971
1311
|
`<meta property="article:published_time" content="${escapeHtmlAttribute(frontmatter.publishedAt)}" />`,
|
|
972
|
-
`<meta property="article:author" content="${escapeHtmlAttribute(
|
|
1312
|
+
`<meta property="article:author" content="${escapeHtmlAttribute(words.author.name)}" />`,
|
|
973
1313
|
];
|
|
974
|
-
for (const tag of
|
|
975
|
-
articleMetaLines.push(
|
|
976
|
-
`<meta property="article:tag" content="${escapeHtmlAttribute(tag as unknown as string)}" />`,
|
|
977
|
-
);
|
|
1314
|
+
for (const tag of words.tags) {
|
|
1315
|
+
articleMetaLines.push(`<meta property="article:tag" content="${escapeHtmlAttribute(tag)}" />`);
|
|
978
1316
|
}
|
|
979
1317
|
|
|
980
1318
|
const siteNameAttr = escapeHtmlAttribute(rootConfig.seo.siteName);
|
|
@@ -989,6 +1327,7 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
|
|
|
989
1327
|
pagePayloads: [
|
|
990
1328
|
buildBlogPostStructuredDataPayload({
|
|
991
1329
|
frontmatter,
|
|
1330
|
+
words,
|
|
992
1331
|
canonicalUrl,
|
|
993
1332
|
siteOrigin,
|
|
994
1333
|
siteName: rootConfig.seo.siteName,
|
|
@@ -1022,8 +1361,10 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
|
|
|
1022
1361
|
|
|
1023
1362
|
## `createWebsiteBlogPostBridgeIsland` — per-locale island factory
|
|
1024
1363
|
|
|
1025
|
-
|
|
1026
|
-
|
|
1364
|
+
Imported from `@wildo-ai/saas-website/mdx`; the `/astro-island` entry point deliberately does not export it.
|
|
1365
|
+
`BLOG_POST_PAGE_REF`, the page ref every post shares, is a plain constant exported from `@wildo-ai/saas-website`.
|
|
1366
|
+
|
|
1367
|
+
The structural fix for Astro's React-context propagation gap. Returns a single React island per locale that
|
|
1027
1368
|
encapsulates the entire post tree (BlogPost + MDX body + embedded
|
|
1028
1369
|
sections) inside ONE hydration boundary. Closes over the per-locale
|
|
1029
1370
|
`slugToMdxBody` map (built from `import.meta.glob`) + the navigation
|
|
@@ -1044,7 +1385,7 @@ primitives as island props.
|
|
|
1044
1385
|
* React island a consumer's per-locale `*.bridge.tsx` module exports for
|
|
1045
1386
|
* mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`
|
|
1046
1387
|
* but adapted to the dynamic-routing constraint of the marketing-blog
|
|
1047
|
-
* adapter
|
|
1388
|
+
* adapter.
|
|
1048
1389
|
*
|
|
1049
1390
|
* # Why blog posts cannot reuse the page bridge factory
|
|
1050
1391
|
*
|
|
@@ -1056,10 +1397,10 @@ primitives as island props.
|
|
|
1056
1397
|
* load time — the page bridge closes over it. A blog post's body
|
|
1057
1398
|
* is the compiled MDX module, which varies per slug. Closing the
|
|
1058
1399
|
* MDX body inside the factory at module load time would force one
|
|
1059
|
-
* bridge file per post
|
|
1400
|
+
* bridge file per post, where the contract is one MDX file per post.
|
|
1060
1401
|
* Instead, the factory closes over a `slugToMdxBody: Record<string,
|
|
1061
1402
|
* ComponentType>` map — typically built from
|
|
1062
|
-
* `import.meta.glob('
|
|
1403
|
+
* `import.meta.glob('../content/blog/<segment>/*.mdx', { eager: true, query: '?website-react-mdx' })` (the locale code lower-cased)
|
|
1063
1404
|
* on the consumer side — and the island accepts the active `slug`
|
|
1064
1405
|
* as a primitive (JSON-serializable) prop.
|
|
1065
1406
|
*
|
|
@@ -1068,7 +1409,7 @@ primitives as island props.
|
|
|
1068
1409
|
* `<BlogPost>` renderer ALREADY wraps its tree in
|
|
1069
1410
|
* `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework
|
|
1070
1411
|
* reserves the page ref for the entire blog surface — see
|
|
1071
|
-
* `BLOG_POST_PAGE_REF` JSDoc
|
|
1412
|
+
* `BLOG_POST_PAGE_REF`'s JSDoc, exported from `@wildo-ai/saas-website`). Reusing the page
|
|
1072
1413
|
* bridge would double-wrap the layout. This factory instead
|
|
1073
1414
|
* provides the runtime context and yields directly to `<BlogPost>`,
|
|
1074
1415
|
* which owns the layout boundary itself.
|
|
@@ -1114,9 +1455,9 @@ primitives as island props.
|
|
|
1114
1455
|
*
|
|
1115
1456
|
* `import.meta.glob({ eager: true })` materializes EVERY post's
|
|
1116
1457
|
* compiled JS into the per-locale React-island bundle (~5–20 KB per
|
|
1117
|
-
* post depending on length and embedded section count). For
|
|
1118
|
-
*
|
|
1119
|
-
*
|
|
1458
|
+
* post depending on length and embedded section count). For a blog of
|
|
1459
|
+
* ten or so posts this is fine and matches the documented Astro+MDX
|
|
1460
|
+
* pattern. Past ~50 posts this becomes a real budget concern.
|
|
1120
1461
|
* The factory's API is forward-compatible with `{ eager: false }`
|
|
1121
1462
|
* (lazy loaders): swap the consumer's glob to lazy mode and the
|
|
1122
1463
|
* `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:
|
|
@@ -1129,37 +1470,35 @@ primitives as island props.
|
|
|
1129
1470
|
* **Per-locale bridge file** (consumer side, ONE per locale):
|
|
1130
1471
|
*
|
|
1131
1472
|
* ```tsx
|
|
1132
|
-
* //
|
|
1473
|
+
* // website/src/pages-impl/blog-post-en.bridge.tsx
|
|
1133
1474
|
* import type { ComponentType } from 'react';
|
|
1134
1475
|
*
|
|
1135
|
-
* import { createWebsiteBlogPostBridgeIsland }
|
|
1136
|
-
*
|
|
1137
|
-
* import {
|
|
1138
|
-
*
|
|
1139
|
-
* import {
|
|
1140
|
-
*
|
|
1141
|
-
*
|
|
1142
|
-
* //
|
|
1143
|
-
* //
|
|
1144
|
-
*
|
|
1145
|
-
* // integration emits (default export = the compiled React component).
|
|
1146
|
-
* const rawModules = import.meta.glob('./content/blog/en/*.mdx', {
|
|
1476
|
+
* import { createWebsiteBlogPostBridgeIsland } from '@wildo-ai/saas-website/mdx';
|
|
1477
|
+
*
|
|
1478
|
+
* import { generatedFrontendProviderModules } from '../generated/frontend-providers.generated';
|
|
1479
|
+
* import { FooterComponent } from '../components/FooterComponent';
|
|
1480
|
+
* import { HeaderComponent } from '../components/HeaderComponent';
|
|
1481
|
+
* import { BLOG_POST_MDX_COMPONENTS } from './blog-post.mdx-components';
|
|
1482
|
+
*
|
|
1483
|
+
* // A static glob — Vite resolves it at build time, so the pattern and every option are literals. The query makes
|
|
1484
|
+
* // `websiteBlogReactMdx()` (astro.config) compile these posts for React, so the body renders inside the island.
|
|
1485
|
+
* const rawModules = import.meta.glob('../content/blog/en/*.mdx', {
|
|
1147
1486
|
* eager: true,
|
|
1148
|
-
*
|
|
1487
|
+
* query: '?website-react-mdx',
|
|
1488
|
+
* }) as Record<string, { default: ComponentType<unknown> }>;
|
|
1149
1489
|
*
|
|
1150
|
-
* const slugToMdxBody: Record<string, ComponentType
|
|
1490
|
+
* const slugToMdxBody: Record<string, ComponentType<unknown>> = {};
|
|
1151
1491
|
* for (const [path, mod] of Object.entries(rawModules)) {
|
|
1152
|
-
* // '
|
|
1153
|
-
*
|
|
1154
|
-
* slugToMdxBody[slug] = mod.default;
|
|
1492
|
+
* // '../content/blog/en/why-context.mdx' -> 'why-context'
|
|
1493
|
+
* slugToMdxBody[path.split('/').pop()!.replace(/\.mdx$/, '')] = mod.default;
|
|
1155
1494
|
* }
|
|
1156
1495
|
*
|
|
1157
|
-
* export const BlogPostEnBridgeIsland =
|
|
1158
|
-
*
|
|
1159
|
-
*
|
|
1160
|
-
*
|
|
1161
|
-
*
|
|
1162
|
-
*
|
|
1496
|
+
* export const BlogPostEnBridgeIsland = createWebsiteBlogPostBridgeIsland({
|
|
1497
|
+
* frontendProviderModules: generatedFrontendProviderModules,
|
|
1498
|
+
* slugToMdxBody,
|
|
1499
|
+
* navigation: { headerComponent: HeaderComponent, footerComponent: FooterComponent },
|
|
1500
|
+
* mdxComponents: BLOG_POST_MDX_COMPONENTS,
|
|
1501
|
+
* });
|
|
1163
1502
|
* ```
|
|
1164
1503
|
*
|
|
1165
1504
|
* **Per-locale `[slug].astro` shell** (consumer side):
|
|
@@ -1171,37 +1510,54 @@ primitives as island props.
|
|
|
1171
1510
|
* loadWebsitePageRuntime,
|
|
1172
1511
|
* renderBlogPostHeadHtml,
|
|
1173
1512
|
* renderWebsiteDesignTokensCss,
|
|
1513
|
+
* resolveWebsiteBlogPostCover,
|
|
1174
1514
|
* } from '@wildo-ai/saas-website/astro';
|
|
1515
|
+
* import { resolveWebsiteBlogPostWords } from '@wildo-ai/saas-website';
|
|
1175
1516
|
* import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';
|
|
1176
1517
|
* import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';
|
|
1177
1518
|
* import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';
|
|
1519
|
+
* import { BLOG_VOCABULARY } from '@/blog-vocabulary';
|
|
1178
1520
|
* import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';
|
|
1179
1521
|
*
|
|
1180
1522
|
* export async function getStaticPaths() {
|
|
1181
1523
|
* const posts = await getCollection('blog');
|
|
1182
1524
|
* const defaultLocale = WEBSITE_SITE_CONTEXT.websiteConfig.defaultLocale;
|
|
1183
|
-
*
|
|
1184
|
-
*
|
|
1185
|
-
*
|
|
1525
|
+
* // The collection is `passthrough`, so `post.data` is untyped: parse it to read the locale and slug.
|
|
1526
|
+
* const parsed = posts.map((post) => ({ post, frontmatter: parseBlogPostFrontmatter(post.data, { source: post.id }) }));
|
|
1527
|
+
* return parsed
|
|
1528
|
+
* .filter(({ frontmatter }) => frontmatter.locale === defaultLocale)
|
|
1529
|
+
* .map(({ post, frontmatter }) => ({
|
|
1530
|
+
* params: { slug: frontmatter.slug as string },
|
|
1531
|
+
* // The locales this post is translated into, so the switcher sends the others home rather than to a 404.
|
|
1532
|
+
* props: { entry: post, pageLocales: parsed.filter((o) => o.frontmatter.slug === frontmatter.slug).map((o) => o.frontmatter.locale) },
|
|
1533
|
+
* }));
|
|
1186
1534
|
* }
|
|
1187
|
-
* const { entry } = Astro.props;
|
|
1535
|
+
* const { entry, pageLocales } = Astro.props;
|
|
1188
1536
|
*
|
|
1189
1537
|
* const runtime = loadWebsitePageRuntime({
|
|
1190
1538
|
* manifest: BLOG_POST_PAGE_MANIFEST,
|
|
1191
1539
|
* siteContext: WEBSITE_SITE_CONTEXT,
|
|
1192
1540
|
* labelPacksDir: './src/i18n',
|
|
1193
1541
|
* astroLocale: Astro.currentLocale,
|
|
1542
|
+
* routeParams: Astro.params,
|
|
1194
1543
|
* });
|
|
1195
1544
|
* const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
|
|
1545
|
+
* // The cover with its size: measured from public/ for a site path, from the frontmatter for a remote image.
|
|
1546
|
+
* const cover = await resolveWebsiteBlogPostCover(frontmatter);
|
|
1196
1547
|
* const headHtml = renderBlogPostHeadHtml({
|
|
1197
1548
|
* siteContext: WEBSITE_SITE_CONTEXT,
|
|
1198
1549
|
* locale: runtime.locale,
|
|
1199
1550
|
* routePath: `/blog/${frontmatter.slug}`,
|
|
1200
1551
|
* frontmatter,
|
|
1552
|
+
* // The author and tags as words, never their refs: they are published as article metadata and JSON-LD.
|
|
1553
|
+
* words: resolveWebsiteBlogPostWords({
|
|
1554
|
+
* authorRef: frontmatter.authorRef,
|
|
1555
|
+
* tags: frontmatter.tags,
|
|
1556
|
+
* vocabulary: BLOG_VOCABULARY,
|
|
1557
|
+
* labelPack: runtime.labelPack,
|
|
1558
|
+
* }),
|
|
1201
1559
|
* });
|
|
1202
|
-
* const designTokensCss = renderWebsiteDesignTokensCss(
|
|
1203
|
-
* WEBSITE_SITE_CONTEXT.rootConfig.designTokens,
|
|
1204
|
-
* );
|
|
1560
|
+
* const designTokensCss = renderWebsiteDesignTokensCss(WEBSITE_SITE_CONTEXT.rootConfig.designTokens);
|
|
1205
1561
|
* ---
|
|
1206
1562
|
* <!doctype html>
|
|
1207
1563
|
* <html lang={runtime.locale}>
|
|
@@ -1216,14 +1572,18 @@ primitives as island props.
|
|
|
1216
1572
|
* client:load
|
|
1217
1573
|
* slug={frontmatter.slug}
|
|
1218
1574
|
* rawFrontmatter={entry.data}
|
|
1575
|
+
* cover={cover}
|
|
1219
1576
|
* source={entry.id}
|
|
1220
1577
|
* locale={runtime.locale}
|
|
1221
1578
|
* defaultLocale={runtime.defaultLocale}
|
|
1579
|
+
* locales={WEBSITE_SITE_CONTEXT.websiteConfig.locales.map((entry) => entry.locale)}
|
|
1580
|
+
* pageLocales={pageLocales}
|
|
1581
|
+
* routePath={`/blog/${frontmatter.slug}`}
|
|
1582
|
+
* appOrigin={WEBSITE_SITE_CONTEXT.websiteConfig.appOrigin}
|
|
1222
1583
|
* labelPack={runtime.labelPack}
|
|
1223
1584
|
* designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}
|
|
1224
|
-
* skipToMainContentLabelKey={
|
|
1225
|
-
*
|
|
1226
|
-
* }
|
|
1585
|
+
* skipToMainContentLabelKey={WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey}
|
|
1586
|
+
* frontendProviders={WEBSITE_SITE_CONTEXT.frontendProviders}
|
|
1227
1587
|
* />
|
|
1228
1588
|
* </body>
|
|
1229
1589
|
* </html>
|
|
@@ -1260,10 +1620,13 @@ export interface CreateWebsiteBlogPostBridgeIslandDeps {
|
|
|
1260
1620
|
/**
|
|
1261
1621
|
* Per-slug map of compiled MDX bodies (each entry is a React
|
|
1262
1622
|
* component — the `.default` export of the MDX module). Typically
|
|
1263
|
-
* built from `import.meta.glob('
|
|
1264
|
-
* { eager: true })` with the path-key
|
|
1623
|
+
* built from `import.meta.glob('../content/blog/<segment>/*.mdx',
|
|
1624
|
+
* { eager: true, query: '?website-react-mdx' })` with the path-key
|
|
1625
|
+
* normalized to the slug. The query is what makes
|
|
1626
|
+
* `websiteBlogReactMdx()` compile the post for React; without it the
|
|
1627
|
+
* body is Astro's compilation and renders nothing in the island. Closed
|
|
1265
1628
|
* over at module-load time so the entire MDX body graph for the
|
|
1266
|
-
* locale lands inside ONE React island bundle
|
|
1629
|
+
* locale lands inside ONE React island bundle — this
|
|
1267
1630
|
* is the structural fix for Astro's React-children context-propagation
|
|
1268
1631
|
* gap (see file preamble).
|
|
1269
1632
|
*
|
|
@@ -1327,6 +1690,12 @@ export interface WebsiteBlogPostBridgeIslandProps {
|
|
|
1327
1690
|
* by the renderer).
|
|
1328
1691
|
*/
|
|
1329
1692
|
rawFrontmatter: unknown;
|
|
1693
|
+
/**
|
|
1694
|
+
* The post's cover with its size, from `resolveWebsiteBlogPostCover(frontmatter)` in the route's `.astro`
|
|
1695
|
+
* frontmatter (it reads the site's `public/`, which an island cannot). Forwarded to `<BlogPost>`, which requires it
|
|
1696
|
+
* exactly when the frontmatter names a cover. A plain `{ src, width, height }`, so it crosses the hydration boundary.
|
|
1697
|
+
*/
|
|
1698
|
+
cover?: WebsiteBlogPostCover;
|
|
1330
1699
|
/**
|
|
1331
1700
|
* Diagnostic source identifier echoed into validation errors —
|
|
1332
1701
|
* typically `entry.id` from Astro's content collection. Optional
|
|
@@ -1341,6 +1710,20 @@ export interface WebsiteBlogPostBridgeIslandProps {
|
|
|
1341
1710
|
* island prop).
|
|
1342
1711
|
*/
|
|
1343
1712
|
defaultLocale: AvailableLanguage;
|
|
1713
|
+
/** Every locale the site publishes, for the header's locale switcher (see the page bridge's `locales`). */
|
|
1714
|
+
locales?: readonly AvailableLanguage[];
|
|
1715
|
+
/**
|
|
1716
|
+
* The locales THIS post exists in — those whose collection holds a post with the same slug. The switcher links
|
|
1717
|
+
* a language the post is not translated into to that language's home rather than to a 404. Absent means every
|
|
1718
|
+
* locale (`WebsiteRuntimeContextValue.pageLocales`).
|
|
1719
|
+
*/
|
|
1720
|
+
pageLocales?: readonly AvailableLanguage[];
|
|
1721
|
+
/**
|
|
1722
|
+
* The post's own route, `/blog/<slug>` — the `routePath` the shell already computes for the page runtime. Forwarded
|
|
1723
|
+
* to the page context so the server-rendered header knows the current page: without it the switcher's links point
|
|
1724
|
+
* at each locale's home until the island hydrates.
|
|
1725
|
+
*/
|
|
1726
|
+
routePath?: string;
|
|
1344
1727
|
/** Already-loaded + already-shape-validated label pack. */
|
|
1345
1728
|
labelPack: LabelPack;
|
|
1346
1729
|
/** Design-token bundle from `WebsiteRootConfig.designTokens`. */
|
|
@@ -1359,6 +1742,8 @@ export interface WebsiteBlogPostBridgeIslandProps {
|
|
|
1359
1742
|
appOrigin?: string;
|
|
1360
1743
|
/** Whether the operator owes a legal notice, from `WEBSITE_SITE_CONTEXT.legalNoticeOwed`, as on ordinary page bridges (#2588). */
|
|
1361
1744
|
legalNoticeOwed?: boolean;
|
|
1745
|
+
/** The public documents the application serves, from `WEBSITE_SITE_CONTEXT.servedPublicDocumentRefs`, as on ordinary page bridges (#2987). */
|
|
1746
|
+
servedPublicDocumentRefs?: readonly WebsitePublicDocumentRef[];
|
|
1362
1747
|
}
|
|
1363
1748
|
|
|
1364
1749
|
const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
|
|
@@ -1382,15 +1767,20 @@ export function createWebsiteBlogPostBridgeIsland(
|
|
|
1382
1767
|
function WebsiteBlogPostBridgeIsland({
|
|
1383
1768
|
slug,
|
|
1384
1769
|
rawFrontmatter,
|
|
1770
|
+
cover,
|
|
1385
1771
|
source,
|
|
1386
1772
|
locale,
|
|
1387
1773
|
defaultLocale,
|
|
1774
|
+
locales,
|
|
1775
|
+
pageLocales,
|
|
1776
|
+
routePath,
|
|
1388
1777
|
labelPack,
|
|
1389
1778
|
designTokens,
|
|
1390
1779
|
skipToMainContentLabelKey,
|
|
1391
1780
|
frontendProviders,
|
|
1392
1781
|
appOrigin,
|
|
1393
1782
|
legalNoticeOwed,
|
|
1783
|
+
servedPublicDocumentRefs,
|
|
1394
1784
|
}: WebsiteBlogPostBridgeIslandProps): ReactNode {
|
|
1395
1785
|
const MdxBody = slugToMdxBody[slug];
|
|
1396
1786
|
if (MdxBody === undefined) {
|
|
@@ -1410,7 +1800,7 @@ export function createWebsiteBlogPostBridgeIsland(
|
|
|
1410
1800
|
throw new Error(
|
|
1411
1801
|
`[blog-post-bridge] No MDX body registered for slug="${slug}". ` +
|
|
1412
1802
|
`The bridge factory's slugToMdxBody map only knows: ${known}. ` +
|
|
1413
|
-
`Verify the consumer's import.meta.glob('...content/blog/<
|
|
1803
|
+
`Verify the consumer's import.meta.glob('...content/blog/<segment>/*.mdx', the locale code lower-cased) ` +
|
|
1414
1804
|
`pattern matches the source file naming.`,
|
|
1415
1805
|
);
|
|
1416
1806
|
}
|
|
@@ -1425,12 +1815,15 @@ export function createWebsiteBlogPostBridgeIsland(
|
|
|
1425
1815
|
const runtimeValue: WebsiteRuntimeContextValue = {
|
|
1426
1816
|
locale,
|
|
1427
1817
|
defaultLocale,
|
|
1818
|
+
...(locales !== undefined ? { locales } : {}),
|
|
1819
|
+
...(pageLocales !== undefined ? { pageLocales } : {}),
|
|
1428
1820
|
labelPack,
|
|
1429
1821
|
designTokens,
|
|
1430
1822
|
navigation,
|
|
1431
1823
|
skipToMainContentLabelKey,
|
|
1432
1824
|
appOrigin,
|
|
1433
1825
|
...(legalNoticeOwed !== undefined ? { legalNoticeOwed } : {}),
|
|
1826
|
+
...(servedPublicDocumentRefs !== undefined ? { servedPublicDocumentRefs } : {}),
|
|
1434
1827
|
...(deps.consentBannerComponent !== undefined ? { consentBannerComponent: deps.consentBannerComponent } : {}),
|
|
1435
1828
|
frontendProviderRegistry,
|
|
1436
1829
|
providerComponentRegistry,
|
|
@@ -1439,8 +1832,10 @@ export function createWebsiteBlogPostBridgeIsland(
|
|
|
1439
1832
|
<WebsiteRuntimeContextProvider value={runtimeValue}>
|
|
1440
1833
|
<BlogPost
|
|
1441
1834
|
rawFrontmatter={rawFrontmatter}
|
|
1835
|
+
{...(cover !== undefined ? { cover } : {})}
|
|
1442
1836
|
source={source}
|
|
1443
1837
|
mdxComponents={mdxComponents}
|
|
1838
|
+
{...(routePath !== undefined ? { routePath } : {})}
|
|
1444
1839
|
>
|
|
1445
1840
|
<MdxBody />
|
|
1446
1841
|
</BlogPost>
|
|
@@ -1451,13 +1846,490 @@ export function createWebsiteBlogPostBridgeIsland(
|
|
|
1451
1846
|
|
|
1452
1847
|
return WebsiteBlogPostBridgeIsland;
|
|
1453
1848
|
}
|
|
1849
|
+
```
|
|
1850
|
+
|
|
1851
|
+
## `websiteBlogReactMdx()` — post bodies compiled for the React island
|
|
1852
|
+
|
|
1853
|
+
## Import Origins
|
|
1854
|
+
|
|
1855
|
+
- `@wildo-ai/saas-website`
|
|
1856
|
+
|
|
1857
|
+
## Source Excerpts
|
|
1858
|
+
|
|
1859
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
1860
|
+
|
|
1861
|
+
```typescript
|
|
1862
|
+
*
|
|
1863
|
+
* `websiteBlogReactMdx()` — the Astro integration that compiles a blog post's body for the React island
|
|
1864
|
+
* that renders it (#2572).
|
|
1865
|
+
*
|
|
1866
|
+
* A post page is ONE React island (the blog bridge), and the body is a React component inside it, so the
|
|
1867
|
+
* body's embedded sections can read the site's labels, tokens and links from the island's context.
|
|
1868
|
+
* `@astrojs/mdx` cannot produce that component: it compiles every `.mdx` module to ASTRO JSX
|
|
1869
|
+
* (`jsxImportSource: "astro"`), which React refuses ("Objects are not valid as a React child"), and it
|
|
1870
|
+
* sets no provider, so the components `BlogPost` hands to `MDXProvider` are never consulted.
|
|
1871
|
+
*
|
|
1872
|
+
* So the bridges import their posts with a query — `import.meta.glob('…/*.mdx', { eager: true, query:
|
|
1873
|
+
* '?website-react-mdx' })`, a literal because Vite takes no other kind there — and this integration compiles exactly those ids with React settings:
|
|
1874
|
+
* `jsxImportSource: 'react'` and `providerImportSource: '@mdx-js/react'`, MDX's own documented React
|
|
1875
|
+
* setup. `@astrojs/mdx` keeps compiling the plain `.mdx` ids (its filter is `/\.mdx$/`, which a
|
|
1876
|
+
* query-suffixed id does not match), so the content collection, its frontmatter and `render()` are
|
|
1877
|
+
* untouched.
|
|
1878
|
+
*
|
|
1879
|
+
* The compiler is the one `@astrojs/mdx` already ships (`@mdx-js/mdx`), resolved from the site's own
|
|
1880
|
+
* `@astrojs/mdx` so the site takes no second MDX dependency to keep in step, with the two remark plugins
|
|
1881
|
+
* `@astrojs/mdx` applies by default: `remark-gfm` (tables, task lists, autolinks) and `remark-smartypants`
|
|
1882
|
+
* (typographic quotes). Nothing else from the site's Markdown setup reaches a post's island body: the site's
|
|
1883
|
+
* own remark and rehype plugins, and Astro's rehype defaults (Shiki code highlighting, heading ids), do not
|
|
1884
|
+
* apply. Style code blocks and link headings in the post's components rather than relying on them.
|
|
1885
|
+
*
|
|
1886
|
+
* Add it beside `mdx()` and `react()`:
|
|
1887
|
+
*
|
|
1888
|
+
* @example
|
|
1889
|
+
* // astro.config.ts
|
|
1890
|
+
* integrations: [mdx(), websiteBlogReactMdx(), react()],
|
|
1891
|
+
*
|
|
1892
|
+
* // a blog bridge (`WEBSITE_REACT_MDX_QUERY`, written as the literal Vite requires)
|
|
1893
|
+
* const rawModules = import.meta.glob('../content/blog/en/*.mdx', { eager: true, query: '?website-react-mdx' });
|
|
1894
|
+
*/
|
|
1895
|
+
|
|
1896
|
+
/** The query without its `?`, as it appears in a module id after the path. */
|
|
1897
|
+
const QUERY_NAME = WEBSITE_REACT_MDX_QUERY.slice(1);
|
|
1898
|
+
|
|
1899
|
+
/** The Vite plugin the integration registers: the subset of Vite's `Plugin` it fills in. */
|
|
1900
|
+
export interface WebsiteBlogReactMdxVitePlugin {
|
|
1901
|
+
readonly name: string;
|
|
1902
|
+
readonly enforce: 'pre';
|
|
1903
|
+
transform(code: string, id: string): Promise<{ code: string; map: null } | null>;
|
|
1904
|
+
}
|
|
1454
1905
|
|
|
1455
1906
|
/**
|
|
1456
|
-
*
|
|
1457
|
-
*
|
|
1458
|
-
*
|
|
1459
|
-
* means the consumer's per-locale bridge file can grab both symbols
|
|
1460
|
-
* from the one `@wildo-ai/saas-website/mdx` import it already has.
|
|
1907
|
+
* The subset of an Astro integration this one uses: structural, so the engine takes no type dependency on Astro, and
|
|
1908
|
+
* exact enough that it is assignable to Astro's `AstroIntegration` (its `updateConfig` takes a deep-partial config,
|
|
1909
|
+
* whose `vite.plugins` accepts this plugin shape).
|
|
1461
1910
|
*/
|
|
1462
|
-
export
|
|
1911
|
+
export interface WebsiteBlogReactMdxIntegration {
|
|
1912
|
+
readonly name: string;
|
|
1913
|
+
readonly hooks: {
|
|
1914
|
+
readonly 'astro:config:setup': (options: {
|
|
1915
|
+
readonly config: { readonly root: URL };
|
|
1916
|
+
readonly updateConfig: (config: {
|
|
1917
|
+
vite: { plugins: WebsiteBlogReactMdxVitePlugin[]; optimizeDeps: { include: string[] } };
|
|
1918
|
+
}) => unknown;
|
|
1919
|
+
}) => void;
|
|
1920
|
+
};
|
|
1921
|
+
}
|
|
1922
|
+
|
|
1923
|
+
/** What the compiler module exports that this integration calls. */
|
|
1924
|
+
interface MdxCompilerModule {
|
|
1925
|
+
compile(
|
|
1926
|
+
source: string,
|
|
1927
|
+
options: {
|
|
1928
|
+
jsxImportSource: string;
|
|
1929
|
+
providerImportSource: string;
|
|
1930
|
+
format: 'mdx';
|
|
1931
|
+
development: boolean;
|
|
1932
|
+
remarkPlugins: unknown[];
|
|
1933
|
+
},
|
|
1934
|
+
): Promise<{ toString(): string }>;
|
|
1935
|
+
}
|
|
1936
|
+
|
|
1937
|
+
/** A module's default export, or the module itself when it has none (CommonJS interop). */
|
|
1938
|
+
function defaultExport(module: unknown): unknown {
|
|
1939
|
+
return typeof module === 'object' && module !== null && 'default' in module ? (module as { default: unknown }).default : module;
|
|
1940
|
+
}
|
|
1941
|
+
|
|
1942
|
+
/**
|
|
1943
|
+
* The MDX compiler and the two Markdown plugins Astro's own MDX compile uses, resolved through the site's
|
|
1944
|
+
* `@astrojs/mdx`. Refuses with the remedy when the site has no `@astrojs/mdx`: a blog needs it anyway, for
|
|
1945
|
+
* its content collection.
|
|
1946
|
+
*/
|
|
1947
|
+
async function loadCompiler(siteRoot: URL): Promise<{ compiler: MdxCompilerModule; remarkPlugins: unknown[] }> {
|
|
1948
|
+
const fromSite = createRequire(new URL('package.json', siteRoot));
|
|
1949
|
+
let astroMdxManifest: string;
|
|
1950
|
+
try {
|
|
1951
|
+
astroMdxManifest = fromSite.resolve('@astrojs/mdx/package.json');
|
|
1952
|
+
} catch {
|
|
1953
|
+
throw new Error(
|
|
1954
|
+
`[saas-website] websiteBlogReactMdx() needs @astrojs/mdx, resolved from ${fileURLToPath(siteRoot)}. `
|
|
1955
|
+
+ 'Install it in the website package and add mdx() to its integrations: the blog content collection needs it too.',
|
|
1956
|
+
);
|
|
1957
|
+
}
|
|
1958
|
+
const fromAstroMdx = createRequire(astroMdxManifest);
|
|
1959
|
+
const importFromAstroMdx = (specifier: string): Promise<unknown> => import(fromAstroMdx.resolve(specifier));
|
|
1960
|
+
const [compiler, remarkGfm, remarkSmartypants] = await Promise.all([
|
|
1961
|
+
importFromAstroMdx('@mdx-js/mdx'),
|
|
1962
|
+
importFromAstroMdx('remark-gfm'),
|
|
1963
|
+
importFromAstroMdx('remark-smartypants'),
|
|
1964
|
+
]);
|
|
1965
|
+
return {
|
|
1966
|
+
compiler: compiler as MdxCompilerModule,
|
|
1967
|
+
remarkPlugins: [defaultExport(remarkGfm), defaultExport(remarkSmartypants)],
|
|
1968
|
+
};
|
|
1969
|
+
}
|
|
1970
|
+
|
|
1971
|
+
/**
|
|
1972
|
+
* The body of a post: the source after its YAML frontmatter. The frontmatter is the collection's (Astro reads
|
|
1973
|
+
* it); the island's component is the body alone.
|
|
1974
|
+
*/
|
|
1975
|
+
export function stripBlogPostFrontmatter(source: string): string {
|
|
1976
|
+
const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(source);
|
|
1977
|
+
return match === null ? source : source.slice(match[0].length);
|
|
1978
|
+
}
|
|
1979
|
+
|
|
1980
|
+
/**
|
|
1981
|
+
* The module a compiled post imports for its components. Vite's dependency scan never sees it — it appears only in
|
|
1982
|
+
* the output of this plugin's transform — so without naming it the dev server meets it on the first post a visitor
|
|
1983
|
+
* opens, optimizes it then and reloads, and the page that triggered it fails once with React's "Invalid hook call"
|
|
1984
|
+
* (measured on a real site). Named up front, it is optimized at startup with React.
|
|
1985
|
+
*/
|
|
1986
|
+
const MDX_PROVIDER_IMPORT_SOURCE = '@mdx-js/react';
|
|
1987
|
+
|
|
1988
|
+
/** Whether a module id is a post imported for the island: `<path>.mdx?website-react-mdx`. */
|
|
1989
|
+
export function isWebsiteReactMdxId(id: string): boolean {
|
|
1990
|
+
const queryStart = id.indexOf('?');
|
|
1991
|
+
if (queryStart === -1) return false;
|
|
1992
|
+
const path = id.slice(0, queryStart);
|
|
1993
|
+
const query = new URLSearchParams(id.slice(queryStart + 1));
|
|
1994
|
+
return path.endsWith('.mdx') && query.has(QUERY_NAME);
|
|
1995
|
+
}
|
|
1996
|
+
|
|
1997
|
+
export function websiteBlogReactMdx(): WebsiteBlogReactMdxIntegration {
|
|
1998
|
+
return {
|
|
1999
|
+
name: 'wildo:website-blog-react-mdx',
|
|
2000
|
+
hooks: {
|
|
2001
|
+
'astro:config:setup': ({ config, updateConfig }) => {
|
|
2002
|
+
let loaded: Promise<{ compiler: MdxCompilerModule; remarkPlugins: unknown[] }> | undefined;
|
|
2003
|
+
updateConfig({
|
|
2004
|
+
vite: {
|
|
2005
|
+
optimizeDeps: { include: [MDX_PROVIDER_IMPORT_SOURCE] },
|
|
2006
|
+
plugins: [
|
|
2007
|
+
{
|
|
2008
|
+
name: 'wildo:website-react-mdx',
|
|
2009
|
+
enforce: 'pre',
|
|
2010
|
+
async transform(code: string, id: string): Promise<{ code: string; map: null } | null> {
|
|
2011
|
+
if (!isWebsiteReactMdxId(id)) return null;
|
|
2012
|
+
loaded ??= loadCompiler(config.root);
|
|
2013
|
+
const { compiler, remarkPlugins } = await loaded;
|
|
2014
|
+
const compiled = await compiler.compile(stripBlogPostFrontmatter(code), {
|
|
2015
|
+
jsxImportSource: 'react',
|
|
2016
|
+
providerImportSource: MDX_PROVIDER_IMPORT_SOURCE,
|
|
2017
|
+
format: 'mdx',
|
|
2018
|
+
development: false,
|
|
2019
|
+
remarkPlugins,
|
|
2020
|
+
});
|
|
2021
|
+
return { code: compiled.toString(), map: null };
|
|
2022
|
+
},
|
|
2023
|
+
},
|
|
2024
|
+
],
|
|
2025
|
+
},
|
|
2026
|
+
});
|
|
2027
|
+
},
|
|
2028
|
+
},
|
|
2029
|
+
};
|
|
2030
|
+
}
|
|
2031
|
+
```
|
|
2032
|
+
|
|
2033
|
+
The query the bridges write as a literal (`WEBSITE_REACT_MDX_QUERY`, exported from
|
|
2034
|
+
`@wildo-ai/saas-website/mdx`, names it for code that inspects a module id):
|
|
2035
|
+
|
|
2036
|
+
## Import Origins
|
|
2037
|
+
|
|
2038
|
+
- `@wildo-ai/saas-website`
|
|
2039
|
+
|
|
2040
|
+
## Source Excerpts
|
|
2041
|
+
|
|
2042
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2043
|
+
|
|
2044
|
+
```typescript
|
|
2045
|
+
*
|
|
2046
|
+
* The query a blog bridge adds to its post imports so `websiteBlogReactMdx()` compiles them for React (#2572).
|
|
2047
|
+
*
|
|
2048
|
+
* A bridge writes it as a LITERAL — Vite requires every `import.meta.glob` option to be one, so a constant cannot be
|
|
2049
|
+
* passed there:
|
|
2050
|
+
*
|
|
2051
|
+
* @example
|
|
2052
|
+
* const rawModules = import.meta.glob('../content/blog/en/*.mdx', { eager: true, query: '?website-react-mdx' });
|
|
2053
|
+
*
|
|
2054
|
+
* A bridge that omits it imports `@astrojs/mdx`'s module instead, compiled to Astro JSX, which a React island cannot
|
|
2055
|
+
* render (React refuses the object it returns as a child; see `websiteBlogReactMdx`). The constant names the literal
|
|
2056
|
+
* for code that checks a module id; it cannot stand in for the literal in the glob itself.
|
|
2057
|
+
*/
|
|
2058
|
+
export const WEBSITE_REACT_MDX_QUERY = '?website-react-mdx';
|
|
2059
|
+
```
|
|
2060
|
+
|
|
2061
|
+
## The blog vocabulary — authors and tags by their words
|
|
2062
|
+
|
|
2063
|
+
## Import Origins
|
|
2064
|
+
|
|
2065
|
+
- `@wildo-ai/saas-website`
|
|
2066
|
+
|
|
2067
|
+
## Source Excerpts
|
|
2068
|
+
|
|
2069
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2070
|
+
|
|
2071
|
+
```typescript
|
|
2072
|
+
*
|
|
2073
|
+
* The words for a blog's identifiers. A post's frontmatter names its author and its tags by REF (`founding-team`,
|
|
2074
|
+
* `product`): identifiers, which a reader must never see as text. Each ref's words are a CHROME label — chrome
|
|
2075
|
+
* because they appear on every blog surface (a post's byline and tags, an index card) and are rendered outside any one
|
|
2076
|
+
* page's sections:
|
|
2077
|
+
*
|
|
2078
|
+
* - an author: `website.chrome.blog-author.<authorRef>` — the name a byline shows ("The product team");
|
|
2079
|
+
* - a tag: `website.chrome.blog-tag.<tag>` — the word a tag chip shows ("Security", "Sécurité").
|
|
2080
|
+
*
|
|
2081
|
+
* A site lists the keys its posts use in `WebsiteRootConfig.chromeLabelKeys` through
|
|
2082
|
+
* `websiteBlogVocabularyLabelKeys(...)`, so the label-pack check demands each one in every locale. A ref nobody
|
|
2083
|
+
* authored renders as its key, which is what a missing label must look like.
|
|
2084
|
+
*
|
|
2085
|
+
* Rejected: showing the ref humanized (`founding-team` → "Founding team"). That is display text invented from an
|
|
2086
|
+
* identifier — untranslatable, unworded by whoever owns the words, and silent about the gap.
|
|
2087
|
+
*/
|
|
2088
|
+
export function websiteBlogAuthorLabelKey(authorRef: string): WebsiteLabelKey {
|
|
2089
|
+
return WebsiteLabelKeySchema.parse(`website.chrome.blog-author.${authorRef}`);
|
|
2090
|
+
}
|
|
2091
|
+
|
|
2092
|
+
/** The chrome label key of one tag's word. See `websiteBlogAuthorLabelKey`. */
|
|
2093
|
+
export function websiteBlogTagLabelKey(tag: string): WebsiteLabelKey {
|
|
2094
|
+
return WebsiteLabelKeySchema.parse(`website.chrome.blog-tag.${tag}`);
|
|
2095
|
+
}
|
|
2096
|
+
|
|
2097
|
+
/**
|
|
2098
|
+
* What kind of author a ref names: one person, or an organization writing as itself ("The product team"). Its
|
|
2099
|
+
* values are schema.org's types, because that is where the distinction is published: a post's `BlogPosting.author`.
|
|
2100
|
+
* Declared by the site with the ref, never guessed from it — a team written up as a `Person` is a false statement to
|
|
2101
|
+
* every search engine that reads the page.
|
|
2102
|
+
*/
|
|
2103
|
+
export enum WebsiteBlogAuthorKind {
|
|
2104
|
+
PERSON = 'Person',
|
|
2105
|
+
ORGANIZATION = 'Organization',
|
|
2106
|
+
}
|
|
2107
|
+
|
|
2108
|
+
/** The refs a site's posts use: each author with its kind, and every tag. */
|
|
2109
|
+
export interface WebsiteBlogVocabulary {
|
|
2110
|
+
readonly authors: Readonly<Record<string, WebsiteBlogAuthorKind>>;
|
|
2111
|
+
readonly tags: readonly string[];
|
|
2112
|
+
}
|
|
2113
|
+
|
|
2114
|
+
/** An author as a page states it: the words its label holds, and its kind. */
|
|
2115
|
+
export interface WebsiteBlogAuthor {
|
|
2116
|
+
readonly name: string;
|
|
2117
|
+
readonly kind: WebsiteBlogAuthorKind;
|
|
2118
|
+
}
|
|
2119
|
+
|
|
2120
|
+
/**
|
|
2121
|
+
* Every chrome key a blog vocabulary needs, once each and in a stable order — what a site adds to its
|
|
2122
|
+
* `chromeLabelKeys`.
|
|
2123
|
+
*/
|
|
2124
|
+
export function websiteBlogVocabularyLabelKeys(vocabulary: WebsiteBlogVocabulary): WebsiteLabelKey[] {
|
|
2125
|
+
const keys = new Set<string>([
|
|
2126
|
+
...Object.keys(vocabulary.authors).map((ref) => websiteBlogAuthorLabelKey(ref)),
|
|
2127
|
+
...vocabulary.tags.map((tag) => websiteBlogTagLabelKey(tag)),
|
|
2128
|
+
]);
|
|
2129
|
+
return [...keys].sort().map((key) => WebsiteLabelKeySchema.parse(key));
|
|
2130
|
+
}
|
|
2131
|
+
|
|
2132
|
+
/** A post's author and tags as its metadata publishes them: words, never refs. */
|
|
2133
|
+
export interface WebsiteBlogPostWords {
|
|
2134
|
+
readonly author: WebsiteBlogAuthor;
|
|
2135
|
+
/** Each tag's word, in the frontmatter's order. */
|
|
2136
|
+
readonly tags: readonly string[];
|
|
2137
|
+
}
|
|
2138
|
+
|
|
2139
|
+
/**
|
|
2140
|
+
* The words a server-rendered surface publishes for a post — its head (`article:author`, `article:tag`) and its JSON-LD
|
|
2141
|
+
* (`author`, `keywords`) — from the page's label pack.
|
|
2142
|
+
*
|
|
2143
|
+
* Refuses rather than falling back, unlike a rendered byline (which shows a missing label as its key): what this
|
|
2144
|
+
* returns leaves the site as metadata a search engine indexes, where a key or a ref would be a published falsehood
|
|
2145
|
+
* nobody sees. Each refusal names the place a site fixes it.
|
|
2146
|
+
*/
|
|
2147
|
+
export function resolveWebsiteBlogPostWords(input: {
|
|
2148
|
+
readonly authorRef: string;
|
|
2149
|
+
readonly tags: readonly string[];
|
|
2150
|
+
readonly vocabulary: WebsiteBlogVocabulary;
|
|
2151
|
+
readonly labelPack: Readonly<Record<string, string>>;
|
|
2152
|
+
}): WebsiteBlogPostWords {
|
|
2153
|
+
// Own entries only: an inherited name (`constructor`, `toString`) is a valid kebab ref and must not read as declared.
|
|
2154
|
+
const kind = Object.hasOwn(input.vocabulary.authors, input.authorRef) ? input.vocabulary.authors[input.authorRef] : undefined;
|
|
2155
|
+
if (kind === undefined) {
|
|
2156
|
+
throw new Error(`[saas-website] Blog author "${input.authorRef}" is not in the site's blog vocabulary. Declare it there with its kind.`);
|
|
2157
|
+
}
|
|
2158
|
+
const word = (key: string, what: string): string => {
|
|
2159
|
+
const value = input.labelPack[key];
|
|
2160
|
+
if (value === undefined) {
|
|
2161
|
+
throw new Error(`[saas-website] Blog ${what} has no words in this locale's label pack. Author "${key}".`);
|
|
2162
|
+
}
|
|
2163
|
+
return value;
|
|
2164
|
+
};
|
|
2165
|
+
const tags = input.tags.map((tag) => {
|
|
2166
|
+
if (!input.vocabulary.tags.includes(tag)) {
|
|
2167
|
+
throw new Error(`[saas-website] Blog tag "${tag}" is not in the site's blog vocabulary. Declare it there.`);
|
|
2168
|
+
}
|
|
2169
|
+
return word(websiteBlogTagLabelKey(tag), `tag "${tag}"`);
|
|
2170
|
+
});
|
|
2171
|
+
return { author: { name: word(websiteBlogAuthorLabelKey(input.authorRef), `author "${input.authorRef}"`), kind }, tags };
|
|
2172
|
+
}
|
|
2173
|
+
```
|
|
2174
|
+
|
|
2175
|
+
## Publication dates in the reader's locale
|
|
2176
|
+
|
|
2177
|
+
## Import Origins
|
|
2178
|
+
|
|
2179
|
+
- `@wildo-ai/saas-website`
|
|
2180
|
+
|
|
2181
|
+
## Source Excerpts
|
|
2182
|
+
|
|
2183
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2184
|
+
|
|
2185
|
+
```typescript
|
|
2186
|
+
*
|
|
2187
|
+
* A publication date as a reader of `locale` writes it ("April 17, 2026", "17 avril 2026"), from the ISO-8601 instant
|
|
2188
|
+
* a post's frontmatter states.
|
|
2189
|
+
*
|
|
2190
|
+
* Formatted in UTC, on purpose: a publication date is a calendar day, and the page is rendered on a server and then
|
|
2191
|
+
* hydrated in the reader's browser. Formatting in the local time zone would let the two disagree — a post published
|
|
2192
|
+
* at 23:30 UTC reads as the next day in Paris — and React would report a hydration mismatch for the day it moved.
|
|
2193
|
+
*
|
|
2194
|
+
* The one formatter for every blog surface (a post's byline, an index card), so the two cannot spell one date
|
|
2195
|
+
* differently.
|
|
2196
|
+
*/
|
|
2197
|
+
export function formatWebsitePublicationDate(iso: string, locale: string): string {
|
|
2198
|
+
return new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' }).format(new Date(iso));
|
|
2199
|
+
}
|
|
2200
|
+
```
|
|
2201
|
+
|
|
2202
|
+
## The blog index — `buildWebsiteBlogIndex` and `useWebsiteBlogIndex`
|
|
2203
|
+
|
|
2204
|
+
`buildWebsiteBlogIndex` is build-time and ASYNC, on `@wildo-ai/saas-website/astro` (it measures covers); each entry
|
|
2205
|
+
carries its post's `cover` with its size.
|
|
2206
|
+
|
|
2207
|
+
## Import Origins
|
|
2208
|
+
|
|
2209
|
+
- `@wildo-ai/saas-website`
|
|
2210
|
+
|
|
2211
|
+
## Source Excerpts
|
|
2212
|
+
|
|
2213
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2214
|
+
|
|
2215
|
+
```typescript
|
|
2216
|
+
*
|
|
2217
|
+
* `WebsiteBlogIndex` — the site's blog posts in ONE locale, newest first, as a page section needs them to list posts:
|
|
2218
|
+
* a "latest from the blog" strip on the home page, a blog index page. Never the bodies; only what a card shows.
|
|
2219
|
+
*
|
|
2220
|
+
* Built at build time from the blog content collection with `buildWebsiteBlogIndex` (`@wildo-ai/saas-website/astro`),
|
|
2221
|
+
* passed to the page's island as `blogIndex`, and read in a section with `useWebsiteBlogIndex()` — the same shape as
|
|
2222
|
+
* the pricing catalogue. So a post listed on the site is a post that exists, with the title and summary its own
|
|
2223
|
+
* frontmatter carries; nothing is copied into the label pack, where it would go stale the day a post is renamed.
|
|
2224
|
+
*/
|
|
2225
|
+
export interface WebsiteBlogIndexEntry {
|
|
2226
|
+
readonly slug: string;
|
|
2227
|
+
readonly title: string;
|
|
2228
|
+
readonly summary: string;
|
|
2229
|
+
/** ISO-8601, as the post's frontmatter states it. Format it for the reader with `Intl.DateTimeFormat`. */
|
|
2230
|
+
readonly publishedAt: string;
|
|
2231
|
+
readonly authorRef: string;
|
|
2232
|
+
readonly tags: readonly string[];
|
|
2233
|
+
/**
|
|
2234
|
+
* The post's cover with its size, resolved at build time (`resolveWebsiteBlogPostCover`), so a card draws it through
|
|
2235
|
+
* `WebsiteImage` at its real ratio. Absent when the post has no cover.
|
|
2236
|
+
*/
|
|
2237
|
+
readonly cover?: WebsiteBlogPostCover;
|
|
2238
|
+
/** The post's route, locale-neutral (`/blog/<slug>`); `WebsiteInternalLink` adds the locale prefix. */
|
|
2239
|
+
readonly routePath: string;
|
|
2240
|
+
}
|
|
2241
|
+
|
|
2242
|
+
export interface WebsiteBlogIndex {
|
|
2243
|
+
/** The locale every entry is written in. */
|
|
2244
|
+
readonly locale: string;
|
|
2245
|
+
readonly entries: readonly WebsiteBlogIndexEntry[];
|
|
2246
|
+
}
|
|
2247
|
+
```
|
|
2248
|
+
|
|
2249
|
+
## Import Origins
|
|
2250
|
+
|
|
2251
|
+
- `@wildo-ai/saas-website`
|
|
2252
|
+
|
|
2253
|
+
## Source Excerpts
|
|
2254
|
+
|
|
2255
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2256
|
+
|
|
2257
|
+
```typescript
|
|
2258
|
+
*
|
|
2259
|
+
* `buildWebsiteBlogIndex` — turns the blog content collection into the `WebsiteBlogIndex` of one locale: every post's
|
|
2260
|
+
* frontmatter validated with `parseBlogPostFrontmatter` (the same validation the post pages run, so a post that would
|
|
2261
|
+
* fail its own page fails the listing too), the locale's posts kept, newest first, optionally the first `limit`, and
|
|
2262
|
+
* each listed post's cover resolved with its size by `resolveWebsiteBlogPostCover` — measured from the file for a cover
|
|
2263
|
+
* the site serves — so a card draws it at its real ratio.
|
|
2264
|
+
*
|
|
2265
|
+
* Build-time and Node-side, because measuring a cover reads the site's `public/`: it lives on the
|
|
2266
|
+
* `@wildo-ai/saas-website/astro` subpath and is ASYNC. Call it in the page's `.astro` frontmatter and pass the result to
|
|
2267
|
+
* the island:
|
|
2268
|
+
*
|
|
2269
|
+
* @example
|
|
2270
|
+
* const blogIndex = await buildWebsiteBlogIndex(await getCollection('blog'), { locale: runtime.locale, limit: 3 });
|
|
2271
|
+
* <LandingBridgeIsland client:idle … blogIndex={blogIndex} />
|
|
2272
|
+
*
|
|
2273
|
+
* `publicDir` is forwarded to the cover resolver; set it only when the site's Astro config moves `publicDir`.
|
|
2274
|
+
*/
|
|
2275
|
+
export interface BuildWebsiteBlogIndexOptions extends ResolveWebsiteBlogPostCoverOptions {
|
|
2276
|
+
/** The locale whose posts are listed. */
|
|
2277
|
+
readonly locale: string;
|
|
2278
|
+
/** At most this many posts, the newest ones. Every post when omitted. */
|
|
2279
|
+
readonly limit?: number;
|
|
2280
|
+
}
|
|
2281
|
+
|
|
2282
|
+
export async function buildWebsiteBlogIndex(
|
|
2283
|
+
collectionEntries: ReadonlyArray<{ readonly id: string; readonly data: unknown }>,
|
|
2284
|
+
options: BuildWebsiteBlogIndexOptions,
|
|
2285
|
+
): Promise<WebsiteBlogIndex> {
|
|
2286
|
+
const listed = collectionEntries
|
|
2287
|
+
.map((entry) => parseBlogPostFrontmatter(entry.data, { source: entry.id }))
|
|
2288
|
+
.filter((frontmatter) => frontmatter.locale === options.locale)
|
|
2289
|
+
.sort((left, right) => right.publishedAt.localeCompare(left.publishedAt))
|
|
2290
|
+
.slice(0, options.limit ?? Number.POSITIVE_INFINITY);
|
|
2291
|
+
const coverOptions = options.publicDir === undefined ? {} : { publicDir: options.publicDir };
|
|
2292
|
+
const entries: WebsiteBlogIndexEntry[] = await Promise.all(
|
|
2293
|
+
listed.map(async (frontmatter) => {
|
|
2294
|
+
const cover = await resolveWebsiteBlogPostCover(frontmatter, coverOptions);
|
|
2295
|
+
return {
|
|
2296
|
+
slug: frontmatter.slug,
|
|
2297
|
+
title: frontmatter.title,
|
|
2298
|
+
summary: frontmatter.summary,
|
|
2299
|
+
publishedAt: frontmatter.publishedAt,
|
|
2300
|
+
authorRef: frontmatter.authorRef,
|
|
2301
|
+
tags: [...frontmatter.tags],
|
|
2302
|
+
...(cover === undefined ? {} : { cover }),
|
|
2303
|
+
routePath: `/blog/${frontmatter.slug}`,
|
|
2304
|
+
};
|
|
2305
|
+
}),
|
|
2306
|
+
);
|
|
2307
|
+
return { locale: options.locale, entries };
|
|
2308
|
+
}
|
|
2309
|
+
```
|
|
2310
|
+
|
|
2311
|
+
## Import Origins
|
|
2312
|
+
|
|
2313
|
+
- `@wildo-ai/saas-website`
|
|
2314
|
+
|
|
2315
|
+
## Source Excerpts
|
|
2316
|
+
|
|
2317
|
+
### Origin Package: `@wildo-ai/saas-website`
|
|
2318
|
+
|
|
2319
|
+
```typescript
|
|
2320
|
+
*
|
|
2321
|
+
* `useWebsiteBlogIndex()` — the posts a section lists, from the page's bridge island. Throws when the page did not pass
|
|
2322
|
+
* one: a "latest posts" section that silently rendered no posts would read as a blog with nothing in it.
|
|
2323
|
+
*/
|
|
2324
|
+
export function useWebsiteBlogIndex(): WebsiteBlogIndex {
|
|
2325
|
+
const { blogIndex } = useWebsiteRuntime();
|
|
2326
|
+
if (blogIndex === undefined) {
|
|
2327
|
+
throw new Error(
|
|
2328
|
+
'[useWebsiteBlogIndex] this page did not pass a blog index to its bridge island. In the page\'s `.astro` '
|
|
2329
|
+
+ 'frontmatter, build it with `await buildWebsiteBlogIndex(await getCollection(\'blog\'), { locale: runtime.locale })` '
|
|
2330
|
+
+ '(the @wildo-ai/saas-website/astro subpath) and pass `blogIndex={blogIndex}` to the island.',
|
|
2331
|
+
);
|
|
2332
|
+
}
|
|
2333
|
+
return blogIndex;
|
|
2334
|
+
}
|
|
1463
2335
|
```
|