docs
    agency-site-kit: Changelog
    v0.14.2.md

    @sonordev/agency-site-kit Changelog

    What changed in each release, for the sites that use the kit. It's pre-1.0, so a breaking change can land in a minor release; the entry says so when it does. Releases before 0.9.0 aren't listed here.

    0.14.2

    Three fixes to what 0.14.1 does when a case study falls back to its own fields. An SEO description, and an SEO title that's more than a one-word name, still ship exactly as written. Nothing was removed or renamed.

    • A fallback description never stops inside a date or on "and". When the 155-character cut lands inside a written date, the date is kept whole the way a figure stays with its unit, so the head never ends (Sept. 7… or (September…. The cut also never ends on and, the, for, a or another word that descriptionProblem in @sonordev/contracts/seo-meta reads as a description cut short. Either way it steps back a word instead, as long as 70 characters are left.
    • A one-word name with more than a brand after the pipe is left as written. 0.14.1 read everything after the last | as a brand, so Northwind | Rebuilding a 40-Year-Old Engineering Brand became Northwind: Web Development case study | Rebuilding…. The kit doesn't know your site's brand when it builds the head, so now only a one-word part after the pipe reads as one: Northwind | Contoso still becomes Northwind: Web Development case study | Contoso, and anything longer, Northwind | Example Studio included, ships as written.
    • mt reads where it sits. formatCategoryLabel('mt-adams') is Mt Adams again (0.14.1 printed MT Adams), and billings-mt is still Billings MT, the way slugLabel in @sonordev/contracts/page-titles reads them. Every other label prints as in 0.14.1.
    • What a site sees. Nothing to change in your code. Only a case study with no SEO description, or with a one-word title, can read differently, the next time its page builds or revalidates.
    • Docs: Fetching and Images, labels and paths say what changed.

    0.14.1

    A case study's page head no longer falls back to a description too long to show or to a title that's a single word. A description an editor writes for search is never cut. Nothing was removed or renamed.

    • A hand-written SEO description ships exactly as written. generatePortfolioMetadata never cuts seo.metaDescription, whatever its length: a search result shortens a long snippet itself, and an ellipsis put in mid-phrase would read worse. An seo.metaTitle ships as written too, unless its name is a single word (below). A blank SEO field, or one that's only spaces, now counts as absent, so the fallback is used instead of shipping spaces.
    • The fallback description is cut to 155 characters or fewer. When there's no SEO description, the case study's own description is used, and some ran past 500 characters. It now keeps whole sentences while they fit (at least 70 characters of them). Sentence ends are read by splitSentences from @sonordev/contracts/sentences, the shared rule Sonor's services use, so abbreviations like Sept. 7, Acme Inc. or est. 1985 never end a sentence. Otherwise it's cut at the last whole word with "…": a figure stays with its unit ($1.2 million is never left as $1.2), and a comma, colon, (, & or / left hanging is dropped first. When the only place to stop is too early to read (one long URL), it's cut at 154 characters with "…". A description that already fits comes back exactly as given, spacing and all, and a record with no description text gets none rather than an empty string. openGraph.description is always the same text.
    • A one-word title becomes "Name: Category case study". A title's name is what comes before its last |, the way Sonor reads every page title, so only a pipe marks a brand: Acme - A New Website for a Roofing Company is a name of several words and is left alone. The SEO title wins when its name is more than one word, then the record's own title. Only when both names are one word (Northwind) does it read Northwind: Web Development case study, from the category's label, else the first service as a service tag reads (Northwind: Next.js Development case study), else Northwind case study. A brand after the last | stays at the end (Northwind | Example Studio becomes Northwind: Web Development case study | Example Studio), and an empty title stays empty, so a page can still tell there's nothing to show.
    • Category and service labels print acronyms in capitals. formatCategoryLabel('seo') is SEO and formatCategoryLabel('ai-automation') is AI Automation; formatServiceTag('seo audit') is SEO Audit and formatServiceTag('ui/ux design') is UI/UX Design. A two-letter state code reads the same way (ky is KY). The casing comes from @sonordev/contracts/page-titles, and every other word prints as before.
    • What a site sees. Nothing to change in your code. A page whose case study has no SEO description and a long one of its own, or a one-word title, gets the new head the next time it builds or revalidates. To say exactly what you want, write an SEO description and an SEO title of two words or more in Sonor: the kit ships both as written.
    • Docs: Fetching says what the head now does, and Images, labels and paths shows the acronym casing.

    0.14.0

    AgencySiteKitLayout now gets Sonor's measurement and privacy choices from site-kit, so a site on it needs none of its own. This version needs @sonordev/site-kit 8.13.0 or later.

    • The layout mounts the Resonance runtime and Sonor's privacy choices. They are the same components SiteKitLayout mounts, so the two layouts behave alike. They sit after your content as childless siblings that wait for the page to be idle, so nothing wraps your page and nothing above the fold is hidden or animated. A site with no measurement configuration in Sonor shows nothing new, though it does load the small runtime (the next item); one with an enabled configuration and no consent manager of its own gets the notice after the visitor's first interaction.
    • A site without a measurement configuration pays a little, and analytics wait. Every site on the layout loads the small runtime when the page is idle and asks Sonor for its measurement configuration. A site without one gets a short "none" answer and shows nothing, and the runtime asks again about every 30 seconds while the page is open. Analytics don't record until that first answer arrives, and stay off for the page view if it can't. See the layout docs.
    • Two new props. measurement (default true) turns the mount off, for an app that mounts its own ResonanceRuntime; a second runtime on a page is refused. privacyChoices (default true) takes false for a site with its own consent manager, or { privacyUrl, launcherLabel, promptMode }.
    • Only where the layout publishes the token. With credential={false}, or without a key, nothing is mounted, since SiteKitLayout beside it already does.
    • Raised peer range. @sonordev/site-kit is now >= 8.13.0, because the layout imports SiteKitMeasurement from @sonordev/site-kit/measurement. Update site-kit first. It's pre-1.0, so this is a minor release with a breaking peer.

    0.13.0

    A new proof-stage section for apps a Lighthouse run can't score, and the fetcher now enforces the contract's rules for it. Nothing was removed or renamed.

    • portfolioVerification is a section type. An app behind a sign-in has a public door and little else a browser can reach, and a Lighthouse score for the door reads as a score for the app. A Verification section is a short list of checks instead, each stating what was checked (label, result, measured), where, the method, the date and, required, the scope: what the check doesn't cover. It reads in the proof stage, after Performance and Speed Comparison, and completes the proof stage on its own once it has a check that can be shown (caseStudyStageStatus; pass each section's data). PortfolioVerificationData and VerificationCheck are the types, and PortfolioSectionDataMap types its data.
    • A check that can't be shown is never printed. getPortfolioItem keeps only the checks the contract accepts (sanitizeVerificationData): every field present, a scope that names a limit, a where a reader can go to (not a placeholder, not an address with a password in it, not localhost or a private network) and a real day from 2000 up to tomorrow in UTC, so a check dated in the future doesn't print. A Verification section none of whose checks qualifies is dropped, so the proof stage it would have opened is skipped like any stage with nothing in it. The kit can see that a limit was written, not that it's true, so a person still reads the scope.
    • verificationChecks(item) reads the checks of the item's first Verification section, in their stored order. A renderer that walks the sections reads each one's own with readVerificationChecks(section.data), which is what the starter does, and verificationLink(where) returns a plain http or https address with a public host as a link and everything else as null, so only a real address becomes one. VERIFICATION_MAX_CHECKS is the most a section lists (eight).
    • The starter CaseStudy template renders it, headed "What we checked", each check with its scope straight under the result, then where, how and when, and each Verification section prints its own checks. A site that already copied the template adds a portfolioVerification case to its own; the quickstart shows the pattern.
    • formatIsoDate asks the contract's isRealDay instead of keeping its own round trip. Its answers don't change.
    • @sonordev/contracts is now ^2.16.0.

    0.12.0

    A case study now reads in four stages, and the kit knows which section belongs to which. One behaviour change, below; the rest is new.

    • The four stages of the story. Every case study reads problem, build, proof, outcome: what the client came in with, what was planned and made, how the finished build measures, what it's doing for them now. The hero sits above the first stage and the CTA below the last. CASE_STUDY_STAGES is the four ids in order, CASE_STUDY_STAGE_COPY gives each a generic name and the question it answers, SECTION_STAGE and sectionStage(type) say which stage a section belongs to. The section list, the stages and the order come from @sonordev/contracts/portfolio, the same copy Sonor's generator writes to and its dashboard edits by. PORTFOLIO_SECTION_TYPES and PORTFOLIO_SECTION_ORDER are re-exported from there.
    • groupedSections(item) returns one group per stage the case study has ({ stage, index, sections }), numbered in order, each with its sections in reading order. A stage with no sections is left out.
    • orderedSections keeps the arc (behaviour change). The stages always read in order; a case study reordered in the dashboard keeps its order within each stage only. Before, a reordered case study rendered in exactly its stored order and could put the results above the challenges. And Performance now reads before Results in the canonical order: the proof comes before the outcome.
    • Your own names for the stages. A site names the four stages in Sonor's Portfolio settings ("Heat", "Shape", "Temper", "Finish"), and getPortfolioStageNames() returns that map from the same endpoint and cache entry as the brand. stageName(names, stage) reads it and falls back to the generic name, so nothing changes for a site that hasn't named them. The work template reads them in the page and passes them down; the local STAGE_NAMES constant it used to carry is gone.
    • item.narrative is what the story says above its sections: a thesis for the whole case study and one lede per stage, written by Sonor for this project (CaseStudyNarrative). stageLede(item, stage) reads the stage's own lede and falls back to its generic question. A malformed narrative is dropped at the fetcher, so a page never fails on one.
    • The thread. PortfolioChallengeItem.id, PortfolioStrategyPhase.resolves and PortfolioResultItem.proves link a challenge to the phase that cleared it and the result that proves it. All optional; older case studies carry none. challengeRefs(item) lists the challenges with the id each is named by (its own, else challengeId(position), the same id Sonor mints), and linkedChallenges(refs, phase.resolves) resolves a phase's or a result's links to those challenges, in order, dropping any that match nothing. A renderer uses the two to print "clears 01, 03" on a phase and "answers 02" on a result, and to anchor each challenge for the link. challengeId and caseStudyFlowProblems are re-exported from the contract.
    • caseStudyStageStatus(sections) reports which stages are complete, for a preview that wants to say so.
    • The starter CaseStudy template renders by stage: the hero, the thesis, one block per stage opened by its number, name and lede, then the CTA. STAGE_NAMES at the top of the file is where a site puts its own words for the four stages.
    • @sonordev/contracts is now ^2.12.0.

    0.11.2

    The kit now has one dependency, @sonordev/contracts (^2.10.0). It's dependency-free and installs with the kit, so there's nothing to add.

    • Site Architecture lists real page titles, never a label made from the path. When a page had no title of its own, the kit used to build a name from its path and capitalize every word of it: /services/ac-repair became "Ac Repair", /faq became "Faq", /smith-and-smith became "Smith And Smith", and a route pattern printed as ":Slug". It doesn't guess anymore.
      • A page with a real title keeps it exactly as Sonor stored it. Sonor takes the | Brand tail and any stray pipes off a title once, when it generates the case study ("Roof Repair | | Northwind Engineering" is stored as "Roof Repair"), and the kit doesn't trim it a second time. A second trim would cut a page whose real name has a pipe in it: "1 Bedroom | 1BR 1BA" lists whole. A case study generated earlier can still carry the brand tail on its page titles until it's regenerated. Because the kit prints the whole title, it checks the whole title: every piece between the pipes has to be a name, so "Floor Plans | /floor-plans/x" (a path behind the name) is left out just like "/floor-plans/x" is.
      • A page without a real title is left out of the list: an empty title, a path where the title should be (/services/ac-repair, or the page's own path written without its slashes, services/ac-repair), an absolute URL, a host and path with no scheme (example.com/services), or a route pattern (:slug, [slug], [...rest], /floor-plans/:slug). Which titles count as an address is one shared rule in @sonordev/contracts (isPageAddress), the same one Sonor uses where it writes the title, so the two can't disagree. A title that only shares the path's word in a name's spelling ("Pricing" for /pricing) is a name and stays. Nothing is ever made from a path.
      • The home page with no title is still "Home". That's a fixed word, not a label made from anything.
      • A group whose pages were all left out keeps its label and count and comes back with pages: []. Render the heading and the count and skip the empty list, so you don't print an empty bullet list. A group's count is the number of pages the client's site has there, so it can be higher than the pages you list.
      • Each page still comes back as { title } only, so raw client-site paths still never reach your page or its client payload.
    • humanizeArchPageEntry keeps its name and its type, and no longer humanizes. It returns { title } as before, but for an entry with no real title it returns { title: '' } where it used to return a label made from the path. If you call it yourself, skip the entries with an empty title. sanitizeSiteArchitectureData, which getPortfolioItem runs for you, does that already.
    • Entries that aren't objects, or whose path or title isn't text, are left out. They used to be listed as "Home" or to throw.

    0.11.1

    • Draft previews open on your domain. The preview route redirected to a full URL built from the incoming request, and on some hosts that isn't the address the visitor asked for: Next builds it from the hostname its server started with, and on Netlify that can be the deploy's own *.netlify.app address. The preview then opened there, without the preview cookies (they're set on your domain), and showed "not found". The route now answers with a relative Location, which the browser resolves against the address it actually requested. The draft-mode and preview cookies ride the same response, as before.
    • The preview token stays out of the address bar. Netlify adds the incoming query to a redirect whose Location has none, so visitors landed on /work/<slug>?slug=…&token=…. The route now redirects to /work/<slug>?preview=1, which Netlify passes through as is. Nothing reads preview=1: draft mode and the cookie are what unlock the draft.
    • basePath loses a trailing slash, as it already did for createRevalidateHandler, so '/work/' no longer redirects to /work//<slug>, and the slug is encoded as one path segment.
    • A basePath that isn't a local path ('work', '//cdn.example.com') now throws a TypeError when the handler is created, as it already did for createRevalidateHandler. A relative redirect to it would leave your site.

    0.11.0

    Breaking for two setups: a site that relied on the dark fallback brand (see getPortfolioBrandConfig below), and a site that set UPTRADE_API_URL without SONOR_API_URL. Everything else is additive.

    • Full docs on sonor.dev. Quickstart, proof and provenance, sections and devices, images and labels, JSON-LD, fetching, types, the brand layout, live updates and preview, live device frames, and a subpath map. The pages ship in the package (docs/, docs.json), and so does this changelog.
    • Source maps no longer ship. The package is smaller, and stepping into the kit from your browser's devtools lands in the built JavaScript.
    • The doc comments on resolvePortfolioImage and the image-typed fields now say what Sonor sends: plain image URLs. SanityImageRef is documented as the older shape those fields no longer carry at runtime. The one-time console warning for a bare image asset ID has new wording. Nothing else changed.
    • One brand fetch. AgencySiteKitLayout now fetches the brand through getPortfolioBrandConfig, which takes optional apiKey and apiUrl. The layout's brand is cached under the portfolio tag, so a brand edit in Sonor refreshes it along with your case studies, and it retries a busy API like the other fetchers do.
    • getPortfolioBrandConfig falls back to DEFAULT_BRAND_CONFIG, the light defaults the layout always used, instead of a separate dark palette, and it merges your brand over those defaults so every field is set. If you relied on the dark fallback, pass your own brand or set theme="dark" on the layout.
    • UPTRADE_API_URL is no longer read. Set SONOR_API_URL, or leave it unset for https://api.sonor.io.

    0.10.1

    • Docs only: the README's examples credit a fictional business. No code changes.

    0.10.0

    Needs @sonordev/site-kit >= 6.5.0, for the portfolio contract's metric provenance. Breaking: the kit renders nothing.

    Every agency site owns its renderer

    PortfolioPage, PortfolioIndex, PortfolioGrid, PortfolioCard, PortfolioSchema, PortfolioLeadCTA, the skeletons and error fallback, every section component, every primitive (DeviceTrifolio, SoloMacBook, ScrollReveal, AnimatedCounter and the rest) and the data-sk-mode stage contract are gone, along with the ./portfolio/client, ./portfolio/sections/*, ./portfolio/primitives/* and ./portfolio/components/* subpaths. Sites that cared how their case studies looked were rebuilding those components anyway. Build them in your site (the setup CLI now scaffolds a starter) and use buildPortfolioJsonLd in place of PortfolioSchema.

    What stays is what every renderer has to agree on:

    • Proof. curatePortfolioProof, gateMetricsDeltas, and metric provenance from @sonordev/site-kit/portfolio/contract (measured, reported, estimated, and reportedBy on a client's number). New: metricCredit (the credit a client's number wears), metricNote (that credit, or Client-reported / Estimated, or nothing for a measured number), headlineKpi (the number a card leads with: measured or attributed-reported, never an estimate, and credited) and formatMetricValue. Every site now leads its cards with the same number and credits a client's figure the same way.
    • Order. PORTFOLIO_SECTION_ORDER, orderedSections (keeps a dashboard reorder, with the hero pinned first), sectionData and projectBrandColor.
    • JSON-LD. buildPortfolioJsonLd (an Article) and jsonLdString, which escapes <.
    • Evidence. getProofRecords(slug, { site }) and the ProofRecord type, for the evidence Sonor publishes behind a case study's numbers.
    • Unchanged: the fetchers and their error contract, the device-stage decisions (shouldRenderSoloDevice, resolveSoloScreenshot), image resolution, the sanitizers and formatters, AgencySiteKitLayout, createRevalidateHandler and createPortfolioPreviewHandler.

    /portfolio, /portfolio/pure and the root entry now export the same pure rules. /portfolio/pure stays for the sites already importing it.

    Setup scaffolds a starter renderer

    agency-site-kit-setup writes app/work/_components/ (CaseStudy, WorkGrid, work.module.css): hero, challenges, strategy, results, testimonial, gallery and call to action, and the index with category links and pagination. It's server-rendered with zero client JavaScript, styled on the --sk-* brand variables, and it's yours to change. The case study page emits Article JSON-LD, and every number you didn't measure carries its note.

    • New flag: --agency-name, the publisher in the JSON-LD.
    • The loading templates are gone (the skeletons were kit components), and the error template no longer imports anything from the kit.
    • The starter is typechecked and rendered against the kit before every release, so a kit change that would break a freshly scaffolded site can't ship.

    Smaller package

    One build (ESM and CommonJS) instead of three, and nothing client-side left in it. The package went from 327 files (2.2 MB unpacked) to 82 (0.5 MB).

    0.9.0

    Needs @sonordev/site-kit >= 6.4.0 (the peer dependency was >= 5.3.0).

    Revalidation is built on site-kit's webhook handler

    createRevalidateHandler is now a configuration of createSeoRevalidationHandler from @sonordev/site-kit/llms, plus the portfolio parts, instead of its own copy of the webhook.

    • Breaking: auth is Authorization: Bearer <SONOR_API_KEY> only, compared in constant time. That's what Sonor sends. x-api-key, ?secret=, a body secret and the REVALIDATION_SECRET variable are no longer accepted, and no other key variable is read. SONOR_API_KEY is read on every call. { secret } still overrides it and may now be a function, called on every request (secret: getSonorApiKey).
    • Validated input. Bodies over 16 KB get a 413. Every path, slug and tag is checked (local paths only, no dot segments even percent-encoded, no query, fragment or [segment]), and one bad value refuses the whole call with a 400 before any cache is touched. Before, any string became a revalidation target.
    • llms.txt and llms-full.txt refresh on every call, with /sitemap.xml.
    • Fixed: detail pages, the sitemap and feeds now regenerate. Paths were revalidated with Next's 'page' type, which matches route files (/work/[slug]/page) rather than URLs, so /work/northwind-engineering, /sitemap.xml and /feed.xml regenerated nothing and only the portfolio tag was doing any work. Literal paths are now untyped.
    • Kept: basePath (default /work) and extraPaths on every call, slug / slugs mapped to ${basePath}/${slug}, the default portfolio tag when a call names none, tags revalidated with the 'max' profile, and revalidateAll regenerating the root layout.
    • Breaking: the response is now { revalidated: string[], tags: string[] } (it was { revalidated: true, targets }), which is what Sonor reads.
    • A tag-only call carrying seo now regenerates the root layout, as it does on every other Sonor site.

    Setup: the revalidate route works, and lands where Sonor calls

    • The generated route destructured a function (export const { POST } = createRevalidateHandler()), so it had no POST and failed to typecheck. It's now export const POST = createRevalidateHandler({ basePath }), and --base-path is passed through (it was ignored).
    • agency-site-kit-setup writes it to app/api/seo-revalidate/route.ts, the URL Sonor calls, instead of app/api/revalidate/route.ts, which Sonor never called.

    Portfolio

    • getPortfolioItem results carry industry_tags (industry categories, primary first) for agency industry pages.